Initiate deposit

The deposit endpoint allows you to request a payment from a customer.

Check the guide!

Follow the step-by-step guide on how to build a payment flow using deposits.

This API call is idempotent, which means it is safe to submit a request with the same depositId multiple times.
Duplicate requests with the same depositId will be ignored with the DUPLICATE_IGNORED status in the response.
Since the request can be rejected, you must check the status in the response for each submitted request. The failureReason in the response will contain information about the reason of the rejection.

Each request can get one of the statuses on initiation:

Status		Description
`ACCEPTED`	Yes	The deposit request has been accepted by pawaPay for processing.
`REJECTED`	No	The deposit request has been rejected. See `failureReason` for details.
`DUPLICATE_IGNORED`	No	The deposit request has been ignored as a duplicate of an already accepted deposit request. Duplication logic relies upon `depositId`.

How to find out the final status of this deposit?

As the pawaPay Merchant API is an asynchronous API, you can find out the final status of the ACCEPTED deposit by either:

Waiting for a callback

If you have configured callbacks, the callback with the final status of the deposit will be delivered to your callback URL.

Checking the status

Or poll the Check Deposit Status endpoint.

Headers related to signatures must only be included if you have enabled “Only accept signed requests”. Read more about it from the pawaPay Dashboard documentation.

Authorizations

Authorization

string

header

required

See Authentication.

Headers

Content-Digest

string<string>

SHA-256 or SHA-512 hash of the request body.

Signature

string<string>

Signature of the request according to RFC-9421.

Signature-Input

string<string>

Signature input according to RFC-9421.

Accept-Signature

string<string>

Expected signature algorithm of the response according to RFC-9421.

Accept-Digest

string<string>

Expected digest algorithm of the response according to RFC-9421.

Body

application/json

depositId

string<uuid>

required

A UUIDv4 based unique ID for this payment. We require you to provide the unique ID for all initiated payments to ensure you can always reconcile all payments. Please store this ID in your system before initiating the payment with pawaPay.

Required string length: 36

Example:

"f4401bd2-1568-4140-bf2d-eb77d2b2b639"

payer

object

required

Details about the customer who is paying or receiving the payment.

Show child attributes

payer.type

enum<string>

required

The type of account involved in the transaction. At the moment, only MMO is supported.

Available options:

MMO

Example:

"MMO"

payer.accountDetails

object

required

Show child attributes

payer.accountDetails.phoneNumber

string

required

The phone number (MSISDN) of the customer paying or receiving payment. The format is described in Wikipedia.

Use predict provider to validate and sanitise the phone number.

Phone number validation has following rules:

Only digits without whitespaces or any other separators or prefixes like '+'.
Should not start with zero.
Country code is mandatory.
Should not exceed or be less than the valid length of specified country.

Example:

"260763456789"

payer.accountDetails.provider

string

required

The provider represents the mobile money operator or processor that can process payments.

Find here a list of all the supported providers.

The active configuration endpoint provides the list of provider configured for your account.

You can use the predict provider enpoint to predict the provider to use based on the phone number (MSISDN).

Example:

"MTN_MOMO_ZMB"

amount

string

required

The amount of the payment.

Amount must follow below requirements or the request will be rejected:

Not all providers support decimals. Find which ones do from providers or dynamically using active configuration endpoint.
Transaction limits apply. Find them from the Active Configuration endpoint.
Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.

Required string length: 1 - 23

Example:

"15"

currency

string

required

The currency in which the amount is specified.

Format must be the ISO 4217 three character currency code in upper case. Read more from Wikipedia.

Find the supported currencies for the provider.

The active configuration endpoint has all the providers configured for your account together with the supported currencies.

Example:

"ZMW"

preAuthorisationCode

string

Provider with 'authType' as 'PREAUTH' will expect the preauthorization token (OTP) to be passed in through this parameter.

Required string length: 1 - 36

clientReferenceId

string

A reference to an entity in your system that this payment relates to. For example, an invoice ID, customer ID etc.

Example:

"INV-123456"

customerMessage

string

A short narration for the transaction. Depending on the 'provider', this message may be visible to the customer in the SMS receipt or within their transaction history.

Defaults to your company name as registered on your pawaPay account trimmed to fit the length limitations.

Required string length: 4 - 22

Example:

"Note of 4 to 22 chars"

metadata

object[]

A list of metadata that you can attach to the payment for providing additional context about the payment. For example, adding the channel from which the payment was initated, product ID or anything else that might help your operations team.

Metadata will be included in:

In the dashboard on payment details pages
Financial statements as JSON object
Callbacks

Metadata can be used when searching in the pawaPay Dashboard. Full value of the metadata field must be used for searches.

Metadata will not be visible to the customer that is involved in this payment.

Up to 10 metadata fields can be attached to a payment.

Show child attributes

metadata.additionalProperties

string

The metadata that you are attaching to the payment. For example "orderId":"ORD-123456789".

Example:

"\"orderId\": \"ORD-123456789\""

metadata.isPII

boolean

default:false

Indicates whether the field contains personally identifiable information. Used for compliance with GDPR or other relevant data privacy laws.

Example:

true

Example:

[
  { "orderId": "ORD-123456789" },
  {
    "customerId": "[email protected]",
    "isPII": true
  }
]

Response

Request has valid payload. See 'status' to confirm if payment was accepted for processing.

depositId

string<uuid>

required

The unique ID for this payment in pawaPay as specified by you during initiation.

Required string length: 36

Example:

"f4401bd2-1568-4140-bf2d-eb77d2b2b639"

status

enum<string>

required

The initiation status of the deposit:

ACCEPTED - The deposit has been accepted by pawaPay for processing.
REJECTED - The deposit has been rejected. See failureReason for details
DUPLICATE_IGNORED - The deposit has been ignored as a duplicate of and already accepted deposit. Deduplication is based on depositId.

Available options:

ACCEPTED,

REJECTED,

DUPLICATE_IGNORED

created

string<date-time>

The timestamp of when the payment was created in the pawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 from IETF

Example:

"2020-02-21T17:32:29Z"

failureReason

object

Show child attributes

failureReason.failureCode

enum<string>

Reason for the failure:

NO_AUTHENTICATION - The API token was not found in the request headers.
AUTHENTICATION_ERROR - The API token in the request headers is not valid.
AUTHORISATION_ERROR - The API Token in the request header is not authorised to make this request.
HTTP_SIGNATURE_ERROR - The signature you have passed with the request did not pass verification.
INVALID_INPUT - We were unable to parse the payload of the request.
MISSING_PARAMETER - A mandatory parameter was missing from the request body.
UNSUPPORTED_PARAMETER - An unsupported parameter was found in the request body.
INVALID_PARAMETER - A parameter had an incorrect value.
DUPLICATE_METADATA_FIELD - A duplicate field was found in payment metadata.
DEPOSITS_NOT_ALLOWED - Deposits are not enabled with the provider on your pawaPay account.
INVALID_PHONE_NUMBER - The phone number provided is in the wrong format.
INVALID_AMOUNT - The amount contains decimals which is not supported by the provider.
AMOUNT_OUT_OF_BOUNDS - The amount is outside of this providers transaction limits.
INVALID_CURRENCY - The currency is not supported by the provider.
INVALID_PROVIDER - The provider is not valid for this request.
PROVIDER_TEMPORARILY_UNAVAILABLE - The provider is not currently not able to accept payments.
UNKNOWN_ERROR - The provider is not valid for this request.

Available options:

NO_AUTHENTICATION,

AUTHENTICATION_ERROR,

AUTHORISATION_ERROR,

HTTP_SIGNATURE_ERROR,

INVALID_INPUT,

MISSING_PARAMETER,

UNSUPPORTED_PARAMETER,

INVALID_PARAMETER,

DUPLICATE_METADATA_FIELD,

DEPOSITS_NOT_ALLOWED,

INVALID_PHONE_NUMBER,

INVALID_AMOUNT,

AMOUNT_OUT_OF_BOUNDS,

INVALID_CURRENCY,

INVALID_PROVIDER,

PROVIDER_TEMPORARILY_UNAVAILABLE,

UNKNOWN_ERROR

failureReason.failureMessage

string

A description of the failure

Deposits

Payouts

Refunds

Remittances

Payment page

Finances

Toolkit

Check the guide!

How to find out the final status of this deposit?

Waiting for a callback

Checking the status

Authorizations

Headers

Body

Response

Deposits

Payouts

Refunds

Remittances

Payment page

Finances

Toolkit

Check the guide!

​How to find out the final status of this deposit?

Waiting for a callback

Checking the status

Authorizations

Headers

Body

Response

How to find out the final status of this deposit?