> ## Documentation Index > Fetch the complete documentation index at: https://docs.pawapay.io/llms.txt > Use this file to discover all available pages before exploring further. # Deposit via Payment Page Initiates a [deposit](/v2/api-reference/deposits/initiate-deposit) using the PawaPay Payment Page. Follow the step-by-step guide on how to build a payment flow using the payment page. * The request will return a `redirectURL`. * The customer should be forwarded to this URL to start the payment process. * Once the customer completes the payment process on the Payment Page, they will be forwarded to the `returnUrl`. * The original `depositId` will be passed as a query parameter. Your page on the `returnUrl` has two options to determine the status of the payment. You can do that by either: If you have configured callbacks, just wait for it. Or poll the Check Deposit Status endpoint. The customer experience of the Payment Page can be changed through the following parameters during initiation. | Parameter | Behaviour if specified | Behaviour if not specified | | --------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `amountDetails` | The specified amount will be used for the payment. Customer is not able to change it. | The customer is able to enter the amount they wish to pay. For example, when depositing into their eWallet. | | `phoneNumber` | The payment will be initiated from the specified mobile money wallet. Customer is not able to change it. | The customer can specify the phone number of the mobile money wallet they wish to pay from. | | `country` | The customer can pay only using a mobile money wallet from the specified country. | The customer can pay with a mobile money wallet from any country that is configured on your PawaPay account. | | `reason` | The reason will be shown to the customer on the Payment Page | The customer will not be shown what they are paying for. | ## OpenAPI ````yaml openapi_v2 post /v2/paymentpage openapi: 3.0.0 info: title: PawaPay Merchant API V2 description: Please find complete documentation from https://docs.pawapay.io/. version: v2 x-logo: url: >- https://global-uploads.webflow.com/62824591015aa314fd308df1/6411b26596e3de3f52551c00_Logopawapay-p-500.png href: https://docs.pawapay.io/ altText: PawaPay logo servers: - url: https://api.sandbox.pawapay.io description: PawaPay Merchant API sandbox - url: https://api.pawapay.io description: PawaPay Merchant API production security: - bearerAuth: [] tags: - name: deposits x-displayName: Deposits - name: split-payments x-displayName: Split Payments - name: checkouts x-displayName: Checkouts - name: payouts x-displayName: Payouts - name: refunds x-displayName: Refunds - name: remittances x-displayName: Remittances - name: payment-page x-displayName: Payment Page - name: toolkit x-displayName: Toolkit - name: finances x-displayName: Finances paths: /v2/paymentpage: post: tags: - payment-page summary: Deposit via Payment Page operationId: create-session requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSession' required: true responses: '200': description: Payment Page session is created successfully content: application/json: schema: $ref: '#/components/schemas/Session' examples: PROVIDER_TEMPORARILY_UNAVAILABLE: value: depositId: f4401bd2-1568-4140-bf2d-eb77d2b2b639 status: REJECTED failureReason: failureCode: PROVIDER_TEMPORARILY_UNAVAILABLE failureMessage: >- The provider 'MTN_MOMO_ZMB' is currently not able to process payments. Please consult our status page for downtime information on all providers. Programmatic access is also available, please consult our API docs. INVALID_PHONE_NUMBER: value: depositId: f4401bd2-1568-4140-bf2d-eb77d2b2b639 status: REJECTED failureReason: failureCode: INVALID_PHONE_NUMBER failureMessage: >- The phone number '2607634' seems to be invalid for the provider 'MTN_MOMO_ZMB'. INVALID_CURRENCY: value: depositId: f4401bd2-1568-4140-bf2d-eb77d2b2b639 status: REJECTED failureReason: failureCode: INVALID_CURRENCY failureMessage: >- The currency 'USD' is not supported with provider 'MTN_MOMO_ZMB'. Please consult API docs for supported currencies. INVALID_AMOUNT: value: depositId: f4401bd2-1568-4140-bf2d-eb77d2b2b639 status: REJECTED failureReason: failureCode: INVALID_AMOUNT failureMessage: >- The provider MTN_MOMO_ZMB only supports up to '2' decimal places in amount. AMOUNT_OUT_OF_BOUNDS: value: depositId: null status: REJECTED failureReason: failureCode: AMOUNT_OUT_OF_BOUNDS failureMessage: >- The amount needs to be more than '1' and less than '20000' for provider 'MTN_MOMO_ZMB'. '400': description: >- Request was rejected due to incompatibility with PawaPay API specification content: application/json: schema: allOf: - $ref: '#/components/schemas/DepositResponseId' - $ref: '#/components/schemas/DepositFailureResponse' examples: INVALID_INPUT: value: depositId: f4401bd2-1568-4140-bf2d-eb77d2b2b639 status: REJECTED failureReason: failureCode: INVALID_INPUT failureMessage: >- We are unable to parse the body of the request. Please consult API documentation for valid request payload. MISSING_PARAMETER: value: depositId: f4401bd2-1568-4140-bf2d-eb77d2b2b639 status: REJECTED failureReason: failureCode: MISSING_PARAMETER failureMessage: >- Request does not include the required parameter 'amount'. INVALID_PARAMETER: value: depositId: f4401bd2-1568-4140-bf2d-eb77d2b2b639 status: REJECTED failureReason: failureCode: INVALID_PARAMETER failureMessage: >- Value for parameter 'provider' is invalid. Please consult API documentation for validation rules. UNSUPPORTED_PARAMETER: value: depositId: f4401bd2-1568-4140-bf2d-eb77d2b2b639 status: REJECTED failureReason: failureCode: UNSUPPORTED_PARAMETER failureMessage: >- Request includes an unsupported parameter 'amnt'. Please remove unsupported parameters from request body. '401': description: >- Authentication failed. Make sure you have added the API token into the header. If using signatures, make sure they are valid. content: application/json: schema: allOf: - $ref: '#/components/schemas/DepositResponseId' - $ref: '#/components/schemas/AuthenticationFailureResponse' examples: AUTHENTICATION_ERROR: value: payoutId: f4401bd2-1568-4140-bf2d-eb77d2b2b639 status: REJECTED failureReason: failureCode: AUTHENTICATION_ERROR failureMessage: The API token in the request is invalid. '403': description: Authorization failure. Please check your authentication token. content: application/json: schema: allOf: - $ref: '#/components/schemas/DepositResponseId' - $ref: '#/components/schemas/AuthorizationFailureResponse' examples: AUTHORISATION_ERROR: value: payoutId: f4401bd2-1568-4140-bf2d-eb77d2b2b639 status: REJECTED failureReason: failureCode: AUTHORISATION_ERROR failureMessage: >- The API token in the request is not authorised for this endpoint. '500': description: An unknown failure has occurred. content: application/json: schema: allOf: - $ref: '#/components/schemas/UnknownFailureResponse' examples: UNKNOWN_ERROR: value: failureReason: failureCode: UNKNOWN_ERROR failureMessage: Unable to process request due to an unknown problem. components: schemas: CreateSession: type: object required: - depositId - returnUrl properties: depositId: $ref: '#/components/schemas/InitiationPaymentId' returnUrl: $ref: '#/components/schemas/ReturnUrl' customerMessage: $ref: '#/components/schemas/CustomerMessage' amountDetails: $ref: '#/components/schemas/AmountDetails' phoneNumber: $ref: '#/components/schemas/PhoneNumber' language: type: string description: > The language in which the Payment Page will be presented to the customer. If the user has explicitly changed their languages preferences, their selection will override this parameter. example: EN enum: - EN - FR country: type: string description: > If specifified, allows payment from phone numbers only from a specific country. If not specified, the customer can select any country that is configured for your account in PawaPay. You can use the [active configuration](/v2/api-reference/toolkit/active-configuration) endpoint to verify which countries and providers have been configured for your account. Format must be the ISO 3166-1 alpha-3, three character country code in upper case. Read more from [Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements). example: ZMB reason: type: string minLength: 1 maxLength: 50 description: >- An optional text which will be displayed to the customer on the payment page to specify what they are paying for. example: Ticket to festival metadata: $ref: '#/components/schemas/TransactionMetadataRequest' Session: type: object properties: redirectUrl: type: string format: uri description: > The unique URL for this Payment Page. Customer has to be forwarded to this URL where they can complete the payment. **Please note! The URL is valid for 15 minutes.** example: >- https://paywith.pawapay.io/?token=AgV4aA3ZxKfGcdMIo6a6Upf7X2MRptdFUrc6Oi3U53CxC0YAkAADABVhd3MtY3J5cHRvLXB1YmxpYy1rZXkAREFzdDR5WktOeWVTRTZ5bTdhVTJJeno3bG1ydkFYenFpUWZqNVQxbGQ2RUgweEpkZVZ0cWJGM3hwMzI1VWN6VGxEdz09AAdwdXJwb3NlAA5jcmVhdGUtc2Vzc2lvbgAFc3RhZ2UAD3NpZ24tY2xvdWRmcm9udAACAAdhd3Mta21zAE5hcm46YXdzOmttczpldS1jZW50cmFsLTE6MTAxOTQ0Mzc3ODY2OmtleS82ZTgzZmVjMS00MWRhLTQxMWQt DepositResponseId: type: object properties: depositId: $ref: '#/components/schemas/ResponsePaymentId' DepositFailureResponse: required: - failureCode - failureMessage type: object properties: status: type: string enum: - REJECTED description: The status of the response will always be `REJECTED` example: REJECTED failureReason: $ref: '#/components/schemas/DepositInitiationFailureReason' AuthenticationFailureResponse: required: - failureCode - failureMessage type: object properties: status: type: string enum: - REJECTED description: The status of the response will always be `REJECTED` example: REJECTED failureReason: $ref: '#/components/schemas/AuthenticationFailureReason' AuthorizationFailureResponse: required: - failureCode - failureMessage type: object properties: status: type: string enum: - REJECTED description: The status of the response will always be `REJECTED` example: REJECTED failureReason: $ref: '#/components/schemas/AuthorizationFailureReason' UnknownFailureResponse: required: - failureCode - failureMessage type: object properties: failureReason: type: object properties: failureCode: type: string description: > Reason for the failure: * `UNKNOWN_ERROR` - Unable to process request due to an unknown problem. example: UNKNOWN_ERROR failureMessage: type: string description: A description of the failure example: Unable to process request due to an unknown problem. InitiationPaymentId: minLength: 36 maxLength: 36 type: string format: uuid description: > 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. example: f4401bd2-1568-4140-bf2d-eb77d2b2b639 ReturnUrl: type: string format: uri description: >- The URL the customer should be redirected to after the payment is processed. example: https://merchant.example.com/checkout-result CustomerMessage: minLength: 4 maxLength: 22 type: string pattern: ^[a-zA-Z0-9 ]+$ description: > 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. example: Note of 4 to 22 chars AmountDetails: type: object properties: amount: $ref: '#/components/schemas/Amount' currency: $ref: '#/components/schemas/Currency' PhoneNumber: type: string description: > The phone number (MSISDN) of the customer paying or receiving payment. The format is described in [Wikipedia](https://en.wikipedia.org/wiki/MSISDN). Use [predict provider](/v2/api-reference/toolkit/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' TransactionMetadataRequest: description: > 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. type: array items: $ref: '#/components/schemas/TransactionMetadataRequestItem' example: - orderId: ORD-123456789 - customerId: customer@email.com isPII: true ResponsePaymentId: minLength: 36 maxLength: 36 type: string format: uuid description: >- The unique ID for this payment in PawaPay as specified by you during initiation. example: f4401bd2-1568-4140-bf2d-eb77d2b2b639 DepositInitiationFailureReason: required: - failureReason type: object properties: failureCode: type: string description: > 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. enum: - 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 failureMessage: type: string description: A description of the failure AuthenticationFailureReason: required: - failureReason type: object properties: failureCode: type: string description: > 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. * `HTTP_SIGNATURE_ERROR` - The signature you have passed with the request did not pass verification. enum: - NO_AUTHENTICATION - AUTHENTICATION_ERROR - HTTP_SIGNATURE_ERROR failureMessage: type: string description: A description of the failure AuthorizationFailureReason: required: - failureReason type: object properties: failureCode: type: string description: > Reason for the failure: * `AUTHORISATION_ERROR` - The API Token in the request header is not authorised to make this request. * `DEPOSITS_NOT_ALLOWED` - Deposits are not enabled with the provider on your PawaPay account. * `PAYOUTS_NOT_ALLOWED` - Payouts are not enabled with the provider on your PawaPay account. * `REMITTANCES_NOT_ALLOWED` - Remittances are not enabled with the provider on your PawaPay account. * `REFUNDS_NOT_ALLOWED` - Refunds are not enabled with the provider on your PawaPay account. enum: - AUTHORISATION_ERROR - DEPOSITS_NOT_ALLOWED - PAYOUTS_NOT_ALLOWED - REMITTANCES_NOT_ALLOWED - REFUNDS_NOT_ALLOWED failureMessage: type: string description: A description of the failure Amount: minLength: 1 maxLength: 23 type: string pattern: ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])?$ description: > 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](/v2/docs/providers) or dynamically using [active configuration](/v2/api-reference/toolkit/active-configuration) endpoint. * Transaction limits apply. Find them from the [Active Configuration](/v2/api-reference/toolkit/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. example: '15' Currency: type: string description: > 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](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). Find the supported currencies for the [provider](/v2/docs/providers). The [active configuration](/v2/api-reference/toolkit/active-configuration) endpoint has all the providers configured for your account together with the supported currencies. example: ZMW TransactionMetadataRequestItem: type: object properties: additionalProperties: type: string description: >- The metadata that you are attaching to the payment. For example `"orderId":"ORD-123456789"`. example: '"orderId": "ORD-123456789"' isPII: type: boolean default: false description: >- 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: customer@email.com isPII: true securitySchemes: bearerAuth: type: http description: >- See [Authentication](/v2/docs/how_to_start#how-to-authenticate-calls-to-the-merchant-api). scheme: bearer bearerFormat: JWT ````