pawaPay Merchant API

https://docs.pawapay.io/v1/api-reference
Admin
The pawaPay Merchant API provides an asynchronous interface for merchants to manage payment...
Tokens:112,718
Snippets:530
Trust Score:8.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### 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 <YOUR_API_TOKEN>' \
-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 <token>'
```

--------------------------------

### 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 <YOUR_API_TOKEN>
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 <token>'
```

--------------------------------

### 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 <token>'
```

--------------------------------

### 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 <token>'
```

--------------------------------

### 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 <token>'
```

--------------------------------

### 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 <token>'
```

--------------------------------

### 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 <token>'
```

--------------------------------

### 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
                                        ...
                                    },
                                    ...
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
```
Tokens:
Raw