### Example PawaPay Redirect URL for Payment Session Source: https://docs.pawapay.io/v1/api-reference/v2/docs/payment_page This is an example of the `redirectUrl` provided by PawaPay. Customers are directed to this URL to complete their payment. It contains various parameters such as `token`, `depositId`, `returnUrl`, `amount`, `country`, and `correspondent`. ```URL https://sandbox.paywith.pawapay.io/?token=AgV4iTX%2FzQ2Jryg0teMwiVww5uf2OJYyCVbsZO3ERr8vW80AkAADABVhd3MtY3J5cHRvLXB1YmxpYy1rZXkAREFnWjh5OWZ2enVLNXVlZmRhQ3lwaUs4UCsxU3kyZllSanJtdk81Sis1eWxFYmwxR2VubmgwNkJhSmpMa2t2Y1M1QT09AAdwdXJwb3NlAA5jcmVhdGUtc2Vzc2lvbgAFc3RhZ2UAD3NpZ24tY2xvdWRmcm9udAACAAdhd3Mta21zAE5hcm46YXdzOmttczpldS1jZW50cmFsLTE6NDgwMTk5MzI1NDYzOmtleS9hOWRkZTRkMC1iOTAyLTQ5NzgtYjA5NS1hN2M2N2JiM2Y2YWQAuAECAQB4S2upLB%2B%2FYU%2FEVudxFv5jvmTrgfd74VlX4aL%2Bnszo7yIBKG0J%2Fs4QSpOHpiKVsGFhZAAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDCDncSOhrmk9d5l6NwIBEIA7vkZSLecrmFtub%2FRif%2F6hHTXTiC9%2Bv98fV%2F4VLtkqKFd0vuZgZaWdQBKsHFyTZarMA4fRKtTffzqHNfcAB2F3cy1rbXMATmFybjphd3M6a21zOmV1LWNlbnRyYWwtMTo0ODAxOTkzMjU0NjM6a2V5L2E5ZGRlNGQwLWI5MDItNDk3OC1iMDk1LWE3YzY3YmIzZjZhZAC4AQICAHhLa6ksH79hT8RW53EW%2FmO%2BZOuB93vhWVfhov6ezOjvIgFj2PbqXlPVVqGVyUyAparTAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMq7enbFjL5gp6GpBDAgEQgDviHiuhaSeHyBkKFWzxjPba%2BTawnP2%2Fa0nVA2fkzrkQS9DULIoLgktu8MRodlDwj38nqiR84qCLy3bUNQIAABAAw6RHjDCLE0oV4Sb5i39layxoxK4W%2FYDFy8Ctn5EnHah%2FewL78joydsqjjsR2duOf%2F%2F%2F%2F%2FwAAAAEAAAAAAAAAAAAAAAEAAAEWF8lZFuQT%2FNGvGwYYILR4k9DRCeHxYgKI%2FiTLjdLdq6PcfxFjdr6dxqvsFr0ntNCXnlGawjbUcMQvwNqBFbM5YGlWQC5SNjblK305ycuH8NOTY4U5j%2BWOKwf%2BlKgrSzT1plmHLk6vDDLxxnE2Wbe1nhQMyyUxIHdKoODaAcQl%2BBsMkSLrkfVIFaTQXtGtWSK24ImD%2BOaTijY8OYg06bprnDe6SujDJx7ZbpBrFQZxtvM9MRfsypAFJe5zn5pn2Xwu4W2goyRlweHbqR%2BufqxijYYAOnCSXr6bxDu%2FQtT763HHAzaBiVCI%2FAXYoy62mp%2B1mdICERxeYSls4eteomyjA7vN8ktOCotSm0HBBmsxtsq6EhTKyFK0cWTJrW6992qJqSUv%2BK%2B7AGcwZQIwL%2BT%2BRduDkmGBMn45cRuvV0Hef4Odd9M5CknNBnz9UsXhqGDqeX55PRoFCfEr4gTvAjEA9xOpVLwF%2F1tmKa2CBSeGf0ckK%2BsMRkEnE8CRhRXPCxV0YsYI1mPAr40ZTlfIoM8U&depositId=6f3ae557-334e-48bb-bd73-ff04767b224f&returnUrl=https%3A%2F%2Fmerchant.com%2FreturnUrl&msisdn=233593456789&amount=100&country=GHA&reason=Demo%20payment&language=en&correspondent=MTN_MOMO_GHA&Expires=1748586499&Key-Pair-Id=K28YQ8X3BNV7W5&Signature=Jm6d1iEKKTO5TC1-t2J5-4d4I6AWtMEeyPiCHyytiDiruMZSMhkcPkMVpGI0CFXxnQM9qGA9JmxcB4UcPkM3QTCTSPwmhyWp6FUAjhjR98sRfco2UfTtl1o9TjurcandF~Y5by5FqmWZlVF3QnkbXJjV5-tnPQitmQqyBL5vAhSw9JOUnUIn~dKZMO15V5s~-CL1FiqV1R~lXHrHtyiFBmNvukF1FDZaGAjvPhbcQKHOI5lK~6nzaQJDXP~SyXAGpSlOvoRWru0AuDDP9kdYIK8qT6UsCpNZiJrxx0ByR1Qq494d9ncn2viz0Tla8~6G1qTKgm3Z0lXTB-WgAmGEw__ ``` -------------------------------- ### Pawapay Deposit API V1 Request Payload Example Source: https://docs.pawapay.io/v1/api-reference/v2/docs/upgrade_from_v1 Example of a deposit request payload structure in Pawapay API V1, showing fields like "depositId", "returnUrl", "statementDescription", "amount", and "msisdn". This represents the older version of the API request. ```JSON { "depositId": "5fcea42c-bbe2-469f-9c59-179f6363d0d5", "returnUrl": "https://merchant.com/returnUrl", "statementDescription": "Note of 4 to 22 chars", "amount": "15", "msisdn": "260763456789" } ``` -------------------------------- ### Get Filtered Provider Availability API (V2 Example) Source: https://docs.pawapay.io/v1/api-reference/v2/docs/upgrade_from_v1 This snippet demonstrates how to query the V2 provider availability endpoint with filtering options. It shows a GET request to fetch availability for a specific country (ZMB) and operation type (DEPOSIT), returning a list of configured providers and their operational status. This endpoint now requires authentication. ```HTTP GET https://api.sandbox.pawapay.io/v2/availability?country=ZMB&operationType=DEPOSIT [ { "country": "ZMB", "providers": [ { "provider": "MTN_MOMO_ZMB", "operationTypes": { "DEPOSIT": "OPERATIONAL" } }, { "provider": "AIRTEL_OAPI_ZMB", ``` -------------------------------- ### Get PIN Prompt Revival Instructions Source: https://docs.pawapay.io/v1/api-reference/v2/docs/deposits If "pinPromptRevivable" is true, this snippet shows how to retrieve "pinPromptInstructions" from the active configuration. These instructions guide customers on how to re-trigger the PIN prompt if the initial attempt fails. ```APIDOC ... "pinPromptInstructions": { "channels": [ { "type": "USSD", "displayName": { "en": "Did not get a PIN prompt?", "fr": "N’avez-vous pas reçu la demande de code PIN?" }, ``` -------------------------------- ### Initiate Refund API Success Response Example Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/refunds An example of a successful JSON response (HTTP 200 ACCEPTED) received after a refund initiation request. It includes the unique refund ID, the status of the refund, and the timestamp of its creation. ```JSON { "refundId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639", "status": "ACCEPTED", "created": "2020-10-19T11:17:01Z" } ``` -------------------------------- ### Example JSON Response for Wallet Balances Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/wallet-balances/wallet-balances Illustrates the expected JSON structure returned by a successful GET request to the /v2/wallet-balances endpoint. It shows an array of wallet objects, each containing country, balance, currency, and provider details. ```JSON { "balances": [ { "country": "ZMB", "balance": "21798.03", "currency": "ZMW", "provider": "" }, { "country": "UGA", "balance": "10798.03", "currency": "UGX", "provider": "" } ] } ``` -------------------------------- ### JSON: Deposit Accepted Response Example Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/deposits/initiate-deposit Shows an example of a successful API response for a deposit request, indicating an 'ACCEPTED' status along with the deposit ID and creation timestamp. This is a typical response when a deposit has been successfully initiated for processing. ```JSON { "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639", "status": "ACCEPTED", "created": "2020-10-19T11:17:01Z" } ``` -------------------------------- ### Predict Provider API Response Example Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/toolkit/predict-provider An example of a successful JSON response from the Predict Provider API, showing the detected country, provider, and the normalized MSISDN. ```JSON { "country": "ZMB", "provider": "MTN_MOMO_ZMB", "msisdn": "260763456789" } ``` -------------------------------- ### pawaPay Deposit/Callback Response (V1 Example) Source: https://docs.pawapay.io/v1/api-reference/v2/docs/upgrade_from_v1 This JSON snippet demonstrates the previous structure of a pawaPay deposit or callback response in V1. It includes deprecated fields such as `requestedAmount`, `depositedAmount`, `correspondentIds`, `respondedByPayer`, and `suspiciousActivityReport`, which have been removed or consolidated in V2. ```JSON { "depositId": "919b7674-b61d-4b69-ac58-d74d2b089192", "status": "FAILED", "requestedAmount": "15", "depositedAmount": "0", "currency": "ZMW", "country": "ZMB", "correspondent": "MTN_MOMO_ZMB", "payer": { "type": "MSISDN", "address": { "value": "260763456789" } }, "customerTimestamp": "2020-02-21T17:32:28Z", "statementDescription": "Note of 4 to 22 chars", "created": "2020-02-21T17:32:29Z", "respondedByPayer": "2020-02-21T17:32:30Z", "correspondentIds": { "MTN_INIT": "ABC123", "MTN_FINAL": "DEF456" }, "suspiciousActivityReport": [ { "activityType": "AMOUNT_DISCREPANCY", "comment": "There is a discrepancy between requested and actual deposit amount." } ], "failureReason": { "failureCode": "OTHER_ERROR", "failureMessage": "Payers address is blocked" }, "metadata": { "orderId": "ORD-123456789", "customerId": "customer@email.com" } } ``` -------------------------------- ### Authenticate API Calls with Bearer Token (cURL) Source: https://docs.pawapay.io/v1/api-reference/v2/docs/how_to_start Demonstrates how to authenticate calls to the pawaPay Merchant API using a bearer token in the Authorization header. This example shows a POST request for a payout, including the base URL, content type, and JSON payload. It highlights that API tokens differ between sandbox and production environments and should be securely stored. ```Shell curl -i -X POST \ https://api.sandbox.pawapay.io/payouts \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "payoutId": "33f30946-881d-40bc-8ca2-94aa4cd467ac", "amount": "15", "currency": "ZMW", "recipient": { "type": "MMO", "accountDetails": { "phoneNumber": "260763456789", "provider": "MTN_MOMO_ZMB" } } }' ``` -------------------------------- ### Example Bulk Payout Mixed Response Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/payouts/initiate-bulk-payout This JSON array illustrates various possible statuses for bulk payout requests. It shows examples of 'ACCEPTED', 'DUPLICATE_IGNORED', and 'REJECTED' statuses, including a failure reason for rejected payouts. ```JSON [ { "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639", "status": "ACCEPTED", "created": "2020-10-19T11:17:01Z" }, { "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639", "status": "DUPLICATE_IGNORED", "created": "2020-10-19T10:22:49Z" }, { "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639", "status": "REJECTED", "failureReason": { "failureCode": "AMOUNT_TOO_LARGE", "failureMessage": "Amount should not be greater than 1000" } } ] ``` -------------------------------- ### Pawapay API: Uganda Deposit and Payout Failure Codes Example 2 Source: https://docs.pawapay.io/v1/api-reference/testing_the_api Further examples of failure codes for Deposit and Payout operations in Uganda, demonstrating various error conditions with Ugandan MSISDNs. ```APIDOC | Operation | MSISDN | failureCode | | --- | --- | --- | | Deposit | 256753456019 | PAYER\_LIMIT\_REACHED | | | 256753456039 | PAYMENT\_NOT\_APPROVED | | | 256753456049 | INSUFFICIENT\_BALANCE | | | 256753456069 | OTHER\_ERROR | | | 256753456129 | NO CALLBACK (stuck in SUBMITTED state) | | | 256753456789 | N/A (COMPLETED) | | Payout | 256753456089 | RECIPIENT\_NOT\_FOUND | | | 256753456099 | RECIPIENT\_NOT\_ALLOWED\_TO\_RECEIVE | | | 256753456119 | OTHER\_ERROR | | | 256753456129 | NO CALLBACK (stuck in SUBMITTED state) | | | 256753456789 | N/A (COMPLETED) | ``` -------------------------------- ### Example Successful pawaPay Deposit Status Response Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference Example JSON response for a successful deposit status check, indicating the depositId, its 'ACCEPTED' status, and the creation timestamp. This shows the typical structure of a positive response from the pawaPay deposit status API. ```JSON { "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639", "status": "ACCEPTED", "created": "2020-10-19T11:17:01Z" } ``` -------------------------------- ### Signature Base for Example HTTP Request Source: https://docs.pawapay.io/v1/api-reference/using_the_api This snippet illustrates the structure of the signature base derived from the example deposit request. It includes derived components such as the HTTP method, authority, and path, along with specific headers like signature-date, content-digest, and content-type. It also defines the signature parameters. ```Text "@method": POST "@authority": localhost:8080 "@path": /deposits "signature-date": 2024-05-02T15:36:45.058799Z "content-digest": sha-512=:mXRb9GJnfR/lyXOVfa27Wg+QrRgX3DVhXpQwjxbWoG3BgX7ZHmXLpvQb4il2kxgLjWmj6oSdwDdn5rUAJVYnUw==: "content-type": application/json; charset=UTF-8 "@signature-params": ("@method" "@authority" "@path" "signature-date" "content-digest" "content-type");alg="ecdsa-p256-sha256";keyid="CUSTOMER_TEST_KEY";created=1714653405;expires=1714653465 ``` -------------------------------- ### Example PIN Prompt Revival Instructions Structure Source: https://docs.pawapay.io/v1/api-reference/v2/docs/deposits Illustrates the JSON structure for providing multi-language instructions to customers for reviving a PIN prompt. It includes `text` for direct display, `template` for dynamic content, and `variables` to populate the template. ```JSON { "instructions": { "en": [ { "text": "Dial *115#", "template": "Dial {{shortCode}}", "variables": { "shortCode": "*115#" } }, { "text": "Enter PIN", "template": "Enter PIN", "variables": { "shortCode": "*115#" } } ], "fr": [ { "text": "Composez *115#", "template": "Composez {{shortCode}}", "variables": { "shortCode": "*115#" } }, { "text": "Entrez le code PIN", "template": "Entrez le code PIN", "variables": { "shortCode": "*115#" } } ] } } ``` -------------------------------- ### Example Manual PIN Prompt Instructions Structure Source: https://docs.pawapay.io/v1/api-reference/v2/docs/deposits Demonstrates the JSON structure for `pinPromptInstructions` when the `pinPrompt` value is `MANUAL`. It details `channels` (e.g., USSD), `displayName` for the overall message, and multi-language `instructions` for specific steps to authorize payment. ```JSON { "pinPromptInstructions": { "channels": [ { "type": "USSD", "displayName": { "en": "Follow the instructions to authorise the payment", "fr": "Veuillez suivre les instructions afin d’autoriser le paiement." }, "instructions": { "en": [ { "text": "Dial *555*6#", "template": "Dial {{shortCode}}", "variables": { "shortCode": "*555*6#" } }, { "text": "Enter PIN", "template": "Enter PIN", "variables": { "shortCode": "*555*6#" } } ], "fr": [ { "text": "Composez *555*6#", "template": "Composez {{shortCode}}", "variables": { "shortCode": "*555*6#" } }, { "text": "Entrez le code PIN", "template": "Entrez le code PIN", "variables": { "shortCode": "*555*6#" } } ] } } ] } } ``` -------------------------------- ### cURL Request to Get Wallet Balances Source: https://docs.pawapay.io/v1/api-reference/v1/api-reference/wallet-balances/wallet-balances Provides a cURL command example for making a GET request to the /v1/wallet-balances endpoint, demonstrating how to include the necessary Authorization header. ```cURL curl --request GET \ --url https://api.sandbox.pawapay.io/v1/wallet-balances \ --header 'Authorization: Bearer ' ``` -------------------------------- ### Example JSON for Preauthorization OTP Generation Instructions Source: https://docs.pawapay.io/v1/api-reference/v2/docs/deposits This JSON structure illustrates the format for retrieving step-by-step instructions for customers to generate a One-Time Password (OTP) for preauthorised payments. It includes multi-language support (English and French) and details specific channels like USSD, typically obtained from the /v2/api-reference/toolkit/active-configuration endpoint. ```json "authTokenInstructions": { "channels": [ { "type": "USSD", "displayName": { "en": "Preauthorization instructions", "fr": "Instructions de préautorisation" }, "instructions": { "en": [ { "text": "Dial *144*4*6#", "template": "Dial {{shortCode}}", "variables": { "shortCode": "*144*4*6#" } }, { "text": "Enter amount", "template": "Enter amount", "variables": { "shortCode": "*144*4*6#" } }, { "text": "Enter PIN", "template": "Enter PIN", "variables": { "shortCode": "*144*4*6#" } }, { "text": "Use OTP", "template": "Use OTP", "variables": { "shortCode": "*144*4*6#" } } ], "fr": [ { "text": "Composez *144*4*6#", "template": "Composez {{shortCode}}", "variables": { "shortCode": "*144*4*6#" } }, { "text": "Entrez le montant", "template": "Entrez le montant", "variables": { "shortCode": "*144*4*6#" } }, { "text": "Entrez le code PIN", "template": "Entrez le code PIN", "variables": { "shortCode": "*144*4*6#" } }, { "text": "Entrez le code à usage unique reçu par SMS", "template": "Entrez le code à usage unique reçu par SMS", "variables": { "shortCode": "*144*4*6#" } } ] } } ] } ``` -------------------------------- ### JSON Response: Public Keys Endpoint Success Example Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/toolkit/public-keys An example of the JSON response returned by the pawaPay Public Keys endpoint upon a successful GET request. It illustrates the structure of the array containing public key objects, each with an 'id' and the 'key' itself. ```JSON [ { "id": "HTTP_EC_P256_KEY:1", "key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEYZe9jhnaZKw9ykMBe2IwRg6AgVMx\n2JRE3RMIdf4YazZTaQaUO19uDI5UO0QsTG699UeI+emd63/GY1PyOpf1rw==\n-----END PUBLIC KEY-----\n" } ] ``` -------------------------------- ### Example HTTP Request to Initiate Deposit Source: https://docs.pawapay.io/v1/api-reference/using_the_api This snippet shows a sample HTTP request for initiating a deposit. It includes essential headers like Authorization, Content-Type, Content-Digest, and Signature-Date, along with a JSON payload detailing the deposit information. ```HTTP Authorization: Bearer Content-Type: application/json; charset=UTF-8 Accept-Encoding: gzip, x-gzip, deflate Content-Digest: sha-512=:mXRb9GJnfR/lyXOVfa27Wg+QrRgX3DVhXpQwjxbWoG3BgX7ZHmXLpvQb4il2kxgLjWmj6oSdwDdn5rUAJVYnUw==: Signature-Date: 2024-05-02T15:36:45.058799Z1714653405;expires=1714653465 Accept-Signature: rsa-pss-sha512,ecdsa-p256-sha256,rsa-v1_5-sha256,ecdsa-p384-sha384 Accept-Digest: sha-256,sha-512 { "depositId": "d6df5c10-bd43-408c-b622-f10f9eaa568b", "amount": "15", "currency": "ZMW", "correspondent": "MTN_MOMO_ZMB", "payer": { "type": "MSISDN", "address": { "value": "260763456789" } }, "customerTimestamp": "2024-05-02T15:36:45.045064Z", "statementDescription": "Signed deposit" } ``` -------------------------------- ### Retrieve Active Configuration for Deposits Source: https://docs.pawapay.io/v1/api-reference/v2/docs/deposits This snippet demonstrates how to query the `active-conf` endpoint to obtain current transaction limits, supported decimal places, and currency information for specific countries and operation types (e.g., DEPOSIT). This data is crucial for validating user inputs and preventing rejections before initiating payments. ```HTTP GET https://api.sandbox.pawapay.io/v2/active-conf?country=BEN&operationType=DEPOSIT ``` ```JSON { "companyName": "Demo", "countries": [ { "country": "BEN", "displayName": { "fr": "Bénin", "en": "Benin" }, "prefix": "229", "providers": [ { "provider": "MOOV_BEN", "nameDisplayedToCustomer": "PAWAPAY", "currencies": [ { "currency": "XOF", "displayName": "CFA", "operationTypes": { "DEPOSIT": { "decimalsInAmount": "NONE", "minAmount": "100", "maxAmount": "2000000" } } } ] }, { "provider": "MTN_MOMO_BEN", "nameDisplayedToCustomer": "PAWAPAY", "currencies": [ { "currency": "XOF", "displayName": "CFA", "operationTypes": { "DEPOSIT": { "decimalsInAmount": "NONE", "minAmount": "100", "maxAmount": "2000000" } } } ] } ] } ] } ``` -------------------------------- ### Resend Deposit Callback API (V2 GET Request) Source: https://docs.pawapay.io/v1/api-reference/v2/docs/upgrade_from_v1 This snippet illustrates the updated V2 API endpoint for resending a deposit callback. In V2, the `depositId` is now passed as a path parameter in a GET request, and the request body is empty, unifying endpoint structures. ```HTTP GET https://api.sandbox.pawapay.io/deposits/resend-callback/919b7674-b61d-4b69-ac58-d74d2b089192 //No body ``` -------------------------------- ### Get Provider Availability Status with cURL Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/toolkit/availability Example cURL command to query the /v2/availability endpoint, requiring an Authorization Bearer token. ```cURL curl --request GET \ --url https://api.sandbox.pawapay.io/v2/availability \ --header 'Authorization: Bearer ' ``` -------------------------------- ### API Documentation for Deposit Initiation Statuses Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference This section details the possible statuses returned by the pawaPay API upon initiating a deposit. It specifies whether a callback is provided for each status and a brief description, including `ACCEPTED`, `REJECTED`, and `DUPLICATE_IGNORED`. ```APIDOC Status | Callback | 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`. ``` -------------------------------- ### Example Response for Payout Initiation Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/payouts/initiate-payout A sample JSON response received after successfully initiating a payout. It includes the unique payout identifier, the processing status (e.g., ACCEPTED), and the timestamp of creation. ```JSON { "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639", "status": "ACCEPTED", "created": "2020-10-19T11:17:01Z" } ``` -------------------------------- ### Check Payout Status with cURL Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/payouts/check-payout-status Example cURL command to retrieve the status of a payout. This command uses a GET request to the specified endpoint and requires a bearer token for authorization. ```cURL curl --request GET \ --url https://api.sandbox.pawapay.io/v2/payouts/{payoutId} \ --header 'Authorization: Bearer ' ``` -------------------------------- ### Example JSON Response for Deposit Initiation Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference This JSON snippet illustrates a successful response from the pawaPay API after a deposit initiation request. It provides the `depositId` of the transaction, its `status` (e.g., ACCEPTED), and the `created` timestamp. ```JSON { "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639", "status": "ACCEPTED", "created": "2020-10-19T11:17:01Z" } ``` -------------------------------- ### Retrieve Active Configuration using cURL Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/toolkit/active-configuration Example cURL command to fetch the active configuration details from the PawaPay sandbox API. This GET request requires an Authorization Bearer token for authentication. ```cURL curl --request GET \ --url https://api.sandbox.pawapay.io/v2/active-conf \ --header 'Authorization: Bearer ' ``` -------------------------------- ### Retrieve Wallet Balances for Country (cURL) Source: https://docs.pawapay.io/v1/api-reference/v1/api-reference/wallet-balances/wallet-balances-for-country Example cURL command to fetch wallet balances for a specified country using a GET request and a Bearer token for authorization against the sandbox API. ```cURL curl --request GET \ --url https://api.sandbox.pawapay.io/v1/wallet-balances/{country} \ --header 'Authorization: Bearer ' ``` -------------------------------- ### Initiate Deposit via PawaPay API Source: https://docs.pawapay.io/v1/api-reference/v2/docs/deposits This API call demonstrates how to initiate a deposit using the PawaPay API's /v2/deposits endpoint. The payload includes a unique deposit ID, amount, currency, and payer details such as phone number and predicted provider. This information is gathered from active configurations, customer input, and your system. ```APIDOC POST https://api.sandbox.pawapay.io/v2/deposits { "depositId": "afb57b93-7849-49aa-babb-4c3ccbfe3d79", "amount": "100", "currency": "RWF", "payer": { "type": "MMO", "accountDetails": { "phoneNumber": "250783456789", "provider": "MTN_MOMO_RWA" } } } ``` -------------------------------- ### cURL Example: Retrieve pawaPay Public Keys Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/toolkit/public-keys A cURL command demonstrating how to make a GET request to the pawaPay Public Keys endpoint. It includes the necessary 'Authorization' header with a placeholder for the Bearer token. ```cURL curl --request GET \ --url https://api.sandbox.pawapay.io/v2/public-key/http \ --header 'Authorization: Bearer ' ``` -------------------------------- ### Example JSON Response for Active Configuration Endpoint Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/toolkit/active-configuration A comprehensive JSON object illustrating the structure of the response from the `/v2/active-conf` endpoint. It includes company details, signature configurations, and a detailed breakdown of countries, providers, currencies, and their supported operation types with specific settings like transaction limits and callback URLs. ```JSON { "companyName": "Merchant Inc.", "signatureConfiguration": { "signedRequestsOnly": true, "signedCallbacks": true }, "countries": [ { "country": "BEN", "displayName": { "en": "Benin", "fr": "Le Benin" }, "prefix": "229", "flag": "https://cdn.com/ben_flag.png", "providers": [ { "provider": "MTN_MOMO_BEN", "displayName": "MTN", "logo": "https://cdn.com/mtn_logo.png", "nameDisplayedToCustomer": "Merchant Inc.", "currencies": [ { "currency": "XOF", "displayName": "KSh", "operationTypes": [ { "DEPOSIT": { "authType": "PROVIDER_AUTH", "pinPrompt": "AUTOMATIC", "pinPromptRevivable": true, "pinPromptInstructions": { "channels": [ { "type": "USSD", "displayName": { "en": "Not getting the PIN prompt?", "fr": "Not getting Le Pin prompt" }, "quickLink": "tel*182*1*3%23", "variables": { "shortCode": "*182#" }, "instructions": { "en": [ { "text": "Dial *182# on your phone", "template": "Dial {{shortCode}} on your phone" } ], "fr": [ { "text": "Composez *182# sur votre téléphone", "template": "Composez {{shortCode}} sur votre téléphone" } ] } } ] }, "minTransactionLimit": "1", "maxTransactionLimit": "1000", "decimalsInAmount": "NONE", "status": "OPERATIONAL", "callbackUrl": "https://merchant.com/depositCallback" } }, { "operationType": "PAYOUT", "minTransactionLimit": "1", "maxTransactionLimit": "1000", "decimalsInAmount": "NONE", "status": "DELAYED", "callbackUrl": "https://merchant.com/payoutCallback" }, { "operationType": "REFUND", "minTransactionLimit": "1", "maxTransactionLimit": "1000", "decimalsInAmount": "NONE", "status": "CLOSED", "callbackUrl": "https://merchant.com/refundCallback" }, { "operationType": "USSD_DEPOSIT", "callbackUrl": "https://merchant.com/ussdCallback" }, { "operationType": "NAME_LOOKUP" } ] } ] } ] } ] } ``` -------------------------------- ### Example Deposit API Success Response Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/deposits A sample JSON response indicating a successful deposit, showing the deposit ID, its 'ACCEPTED' status, and creation timestamp. ```JSON { "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639", "status": "ACCEPTED", "created": "2020-10-19T11:17:01Z" } ``` -------------------------------- ### Check Refund Status with cURL Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/refunds/check-refund-status Retrieves the current status of a refund using its `refundId` via a GET request. This example demonstrates how to make the API call using cURL, requiring an Authorization Bearer token. ```cURL curl --request GET \ --url https://api.sandbox.pawapay.io/v2/refunds/{refundId} \ --header 'Authorization: Bearer ' ``` -------------------------------- ### Successful Refund Initiation API Response Source: https://docs.pawapay.io/v1/api-reference/v2/api-reference/refunds/initiate-refund Example JSON response for a successfully accepted refund initiation. It includes the `refundId`, the `status` of the refund (e.g., ACCEPTED), and the `created` timestamp. ```json { "refundId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639", "status": "ACCEPTED", "created": "2020-10-19T11:17:01Z" } ``` -------------------------------- ### pawaPay API Endpoints for Payment Status and Callbacks Source: https://docs.pawapay.io/v1/api-reference/v2/docs/deposits This section references key pawaPay API endpoints and documentation for checking deposit status, receiving asynchronous callbacks for deposits, payouts, and refunds, and understanding transaction failure codes. ```APIDOC Endpoint: /v2/api-reference/deposits/check-deposit-status Description: Used to verify the status of a deposit, particularly after an UNKNOWN_ERROR. A deposit should only be considered FAILED if it is NOT_FOUND. ``` ```APIDOC Endpoint: /v2/api-reference/deposits/deposit-callback Description: Asynchronous callback for the final status of a deposit. If the status is FAILED, further details are provided via failureCode and failureMessage. ``` ```APIDOC Endpoint: /v2/api-reference/payouts/payout-callback Description: Asynchronous callback for the final status of a payout. ``` ```APIDOC Endpoint: /v2/api-reference/refunds/refund-callback Description: Asynchronous callback for the final status of a refund. ``` ```APIDOC Reference: /v2/docs/failure_codes#transaction-failure-codes Description: Comprehensive documentation of all transaction failure codes to guide custom error handling implementations. ``` -------------------------------- ### Pawapay Deposit API V2 Request Payload Example Source: https://docs.pawapay.io/v1/api-reference/v2/docs/upgrade_from_v1 Example of a deposit request payload structure in Pawapay API V2, demonstrating changes such as "customerMessage" replacing "statementDescription", an "amountDetails" object for "amount" and "currency", and "phoneNumber" replacing "msisdn". This reflects the updated API request format. ```JSON { "depositId": "5fcea42c-bbe2-469f-9c59-179f6363d0d5", "returnUrl": "https://merchant.com/returnUrl", "customerMessage": "Note of 4 to 22 chars", "amountDetails": { "amount": "15", "currency": "ZMW" }, "phoneNumber": "260763456789" } ``` -------------------------------- ### Pawapay API Endpoints for Payout Management Overview Source: https://docs.pawapay.io/v1/api-reference/v2/docs/payouts Overview of key Pawapay API endpoints for managing payout availability and status, including checking provider operational status, retrieving payout details, and cancelling enqueued payouts. This provides a structured reference for API interactions. ```APIDOC Endpoint: GET /v2/availability Description: Checks the operational status of payout providers. Query Parameters: country: string - The country code (e.g., BEN). operationType: string - The type of operation (e.g., PAYOUT). Response Statuses: OPERATIONAL: Provider is available and processing normally. DELAYED: Provider is experiencing downtime; requests are enqueued. CLOSED: Provider is experiencing downtime; requests are rejected. Endpoint: GET /v2/payouts/{payoutId} Description: Retrieves the status of a specific payout. Path Parameters: payoutId: string - Unique identifier for the payout. Response Statuses: ENQUEUED: Payout is queued for processing when the provider becomes operational. ACCEPTED: Payout has been accepted for processing. Endpoint: GET /v2/payouts/fail-enqueued/{payoutId} Description: Cancels an enqueued payout. Path Parameters: payoutId: string - Unique identifier for the payout to cancel. Precondition: Payout must be in 'ENQUEUED' status. Behavior: Asynchronous. Rejects if payout is 'PROCESSING'. Callback: 'FAILED' status received upon successful cancellation. ``` -------------------------------- ### Configure Postman Environment Variables for pawaPay API Source: https://docs.pawapay.io/v1/api-reference/getting_started This snippet provides the necessary environment variables to set up in Postman for interacting with the pawaPay sandbox API. It includes the API token for authentication and the base URL for API requests. ```Postman Configuration Variable | Value --- | --- apiToken | Paste the token you just generated as the value baseUrl | https://api.sandbox.pawapay.io ``` -------------------------------- ### Fetch Active Configuration for Deposits Source: https://docs.pawapay.io/v1/api-reference/v2/docs/deposits This snippet demonstrates how to retrieve the active configuration for your pawaPay account, specifically for deposit operations in a given country. It returns a list of configured providers with their display names and logos, enabling dynamic display of payment options to the customer. This helps in implementing a dynamic deposit flow where new providers are automatically available. ```HTTP GET https://api.sandbox.pawapay.io/v2/active-conf?country=RWA&operationType=DEPOSIT { "companyName": "Demo", "countries": [ { "country": "RWA", "prefix": "250", "flag": "https://static-content.pawapay.io/country_flags/rwa.svg", "displayName": { "en": "Rwanda", "fr": "Rwanda" }, "providers": [ { "provider": "AIRTEL_RWA", "displayName": "Airtel", "logo": "https://static-content.pawapay.io/company_logos/airtel.png", "currencies": [ { "currency": "RWF", "displayName": "R₣", "operationTypes": ... } ] }, { "provider": "MTN_MOMO_RWA", "displayName": "MTN", "logo": "https://static-content.pawapay.io/company_logos/mtn.png", "currencies": [ { "currency": "RWF", "displayName": "R₣", "operationTypes": ... } ] } ] } ] ... } ``` -------------------------------- ### Example PawaPay Refund API Success Response Source: https://docs.pawapay.io/v1/api-reference/v1/api-reference/refunds/check-refund-status This JSON array illustrates a successful response from the PawaPay refund API for a GET /refunds/{refundId} request. It contains an object detailing a single refund transaction, including its ID, status, amount, currency, recipient information, timestamps, and custom metadata. ```JSON [ { "refundId": "8917c345-4791-4285-a416-62f24b6982db", "status": "COMPLETED", "amount": "123.45", "currency": "ZMW", "country": "ZMB", "correspondent": "MTN_MOMO_ZMB", "recipient": { "type": "MSISDN", "address": { "value": "260763456789" } }, "customerTimestamp": "2020-10-19T08:17:00Z", "statementDescription": "From ACME company", "created": "2020-10-19T08:17:01Z", "receivedByRecipient": "2020-10-19T08:17:02Z", "correspondentIds": { "SOME_CORRESPONDENT_ID": "12356789" }, "metadata": { "orderId": "ORD-123456789", "customerId": "customer@email.com" } } ] ``` -------------------------------- ### Initiate Payment Page Session for Any Country Source: https://docs.pawapay.io/v1/api-reference/v2/docs/payment_page This snippet demonstrates how to initiate a payment page session that allows the customer to choose their country and payment amount. It requires a unique depositId generated by the merchant, a returnUrl for redirection after payment, and an optional reason for the payment. ```HTTP POST https://api.sandbox.pawapay.io/v2/widget/session { "depositId": "695776cf-73ba-42ff-b9cb-2b9acc008e22", "returnUrl": "https://merchant.com/returnUrl", "reason": "Demo payment" } ``` -------------------------------- ### Get Active Configuration API Changes (V1 to V2) Source: https://docs.pawapay.io/v1/api-reference/v2/docs/upgrade_from_v1 This snippet details the structural and naming changes in the Active Configuration API response from V1 to V2. Key updates include the removal of `merchantId`, renaming `merchantName` to `companyName`, `correspondents` to `providers`, `ownerName` to `nameDisplayedToCustomer`, and restructuring `currencies` and `operationTypes` with `minAmount`/`maxAmount`. ```APIDOC { "merchantId": "DEMO", //Removed in V2 "merchantName": "DEMO", "countries": [ { "country": "BEN", "correspondents": [ { "correspondent": "MOOV_BEN", "currency": "XOF", "ownerName": "PAWAPAY", "operationTypes": [ { "operationType": "DEPOSIT", "minTransactionLimit": "100", "maxTransactionLimit": "2000000" }, ... ] } ] } ] } ``` ```APIDOC { "companyName": "DEMO", //Was merchantName "countries": [ { "country": "BEN", ... "providers": [ //Was correspondents { "provider": "MOOV_BEN", "nameDisplayedToCustomer": "PAWAPAY", //Was ownerName ... "currencies": [ //Currencies are now an array { "currency": "XOF", "operationTypes": { //Now as a map "DEPOSIT": { "minAmount": "100", //Was minTransactionLimit "maxAmount": "2000000", //Was maxTransactionLimit ... }, ... } } ] } ] } ] } ```