pawaPay Merchant API

https://docs.pawapay.io/v2/
Admin
pawaPay Merchant API enables businesses to send and receive payments using mobile money across...
Tokens:108,391
Snippets:707
Trust Score:8.2
Update:3 months ago
Show doc for...
Tokens:
Raw
### Customer Message Example

Source: https://docs.pawapay.io/v2/api-reference/deposits

Example of a short transaction narration string.

```json
"Note of 4 to 22 chars"
```

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

### Created Timestamp Example

Source: https://docs.pawapay.io/v2/api-reference/deposits

Example of an RFC3339 formatted date-time string.

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

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

### Initiate Refund Request Examples

Source: https://docs.pawapay.io/v2/api-reference/refunds

Examples demonstrating how to send a POST request to the refunds endpoint to initiate a transaction.

```ruby
require 'uri'  
require 'net/http'  
  
url = URI("https://api.sandbox.pawapay.io/v2/refunds")  
  
http = Net::HTTP.new(url.host, url.port)  
http.use_ssl = true  
  
request = Net::HTTP::Post.new(url)  
request["Authorization"] = 'Bearer <token>'  
request["Content-Type"] = 'application/json'  
request.body = "{\n  \"refundId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"depositId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"amount\": \"15\",\n  \"currency\": \"ZMW\",\n  \"clientReferenceId\": \"INV-123456\",\n  \"metadata\": [\n    {\n      \"orderId\": \"ORD-123456789\"\n    },\n    {\n      \"customerId\": \"customer@email.com\",\n      \"isPII\": true\n    }\n  ]\n}"  
  
response = http.request(request)  
puts response.read_body
```

```curl
curl --request POST \
  --url https://api.sandbox.pawapay.io/v2/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "refundId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "amount": "15",
  "currency": "ZMW",
  "clientReferenceId": "INV-123456",
  "metadata": [
    {
      "orderId": "ORD-123456789"
    },
    {
      "customerId": "customer@email.com",
      "isPII": true
    }
  ]
}
'
```

```python
import requests  
  
url = "https://api.sandbox.pawapay.io/v2/refunds"  
  
payload = {  
    "refundId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",  
    "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",  
    "amount": "15",  
    "currency": "ZMW",  
    "clientReferenceId": "INV-123456",  
    "metadata": [  
        { "orderId": "ORD-123456789" },  
        {  
            "customerId": "customer@email.com",  
            "isPII": True  
        }  
    ]  
}  
headers = {  
    "Authorization": "Bearer <token>",  
    "Content-Type": "application/json"  
}  
  
response = requests.post(url, json=payload, headers=headers)  
  
print(response.text)
```

```javascript
const options = {  
  method: 'POST',  
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},  
  body: JSON.stringify({  
    refundId: 'f4401bd2-1568-4140-bf2d-eb77d2b2b639',  
    depositId: 'f4401bd2-1568-4140-bf2d-eb77d2b2b639',  
    amount: '15',  
    currency: 'ZMW',  
    clientReferenceId: 'INV-123456',  
    metadata: [{orderId: 'ORD-123456789'}, {customerId: 'customer@email.com', isPII: true}]  
  })  
};  
  
fetch('https://api.sandbox.pawapay.io/v2/refunds', options)  
  .then(res => res.json())  
  .then(res => console.log(res))  
  .catch(err => console.error(err));
```

```php
<?php  
  
$curl = curl_init();  
  
curl_setopt_array($curl, [  
  CURLOPT_URL => "https://api.sandbox.pawapay.io/v2/refunds",  
  CURLOPT_RETURNTRANSFER => true,  
  CURLOPT_ENCODING => "",  
  CURLOPT_MAXREDIRS => 10,  
  CURLOPT_TIMEOUT => 30,  
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,  
  CURLOPT_CUSTOMREQUEST => "POST",  
  CURLOPT_POSTFIELDS => json_encode([  
    'refundId' => 'f4401bd2-1568-4140-bf2d-eb77d2b2b639',  
    'depositId' => 'f4401bd2-1568-4140-bf2d-eb77d2b2b639',  
    'amount' => '15',  
    'currency' => 'ZMW',  
    'clientReferenceId' => 'INV-123456',  
    'metadata' => [  
        [  
                'orderId' => 'ORD-123456789'  
        ],  
        [  
                'customerId' => 'customer@email.com',  
                'isPII' => true  
        ]  
    ]  
  ]),  
  CURLOPT_HTTPHEADER => [  
    "Authorization: Bearer <token>",  
    "Content-Type: application/json"  
  ],  
]);  
  
$response = curl_exec($curl);  
$err = curl_error($curl);  
  
curl_close($curl);  
  
if ($err) {  
  echo "cURL Error #:" . $err;  
} else {  
  echo $response;  
}
```

```go
package main  
  
import (  
	"fmt"  
	"strings"  
	"net/http"  
	"io"  
)  
  
func main() {  
  
	url := "https://api.sandbox.pawapay.io/v2/refunds"  
  
	payload := strings.NewReader("{\n  \"refundId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"depositId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"amount\": \"15\",\n  \"currency\": \"ZMW\",\n  \"clientReferenceId\": \"INV-123456\",\n  \"metadata\": [\n    {\n      \"orderId\": \"ORD-123456789\"\n    },\n    {\n      \"customerId\": \"customer@email.com\",\n      \"isPII\": true\n    }\n  ]\n}")  
  
	req, _ := http.NewRequest("POST", url, payload)  
  
	req.Header.Add("Authorization", "Bearer <token>")  
	req.Header.Add("Content-Type", "application/json")  
  
	res, _ := http.DefaultClient.Do(req)  
  
	defer res.Body.Close()  
	body, _ := io.ReadAll(res.Body)  
  
	fmt.Println(string(body))  
  
}
```

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

### Statement Date and File Size Examples

Source: https://docs.pawapay.io/v2/api-reference/finances/check-statement-status

Examples of date-time formatting and file size representation for statements.

```text
2025-05-10T10:00:00
```

```text
2025-05-01T10:00:00
```

```text
1048576
```

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

### Client Reference ID Example

Source: https://docs.pawapay.io/v2/api-reference/deposits

Example of a client-side reference identifier.

```json
"INV-123456"
```

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

### CheckoutId Parameter Example

Source: https://docs.pawapay.io/v2/api-reference/checkouts/check-checkout-status

Example value for the checkoutId path parameter.

```yaml
example: f4401bd2-1568-4140-bf2d-eb77d2b2b639
```

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

### Metadata Array Example

Source: https://docs.pawapay.io/v2/api-reference/deposits

Example of an array of metadata objects for additional payment context.

```json
[
  { "orderId": "ORD-123456789" },
  {
    "customerId": "customer@email.com",
    "isPII": true
  }
]
```

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

### CreatedTimestamp Example

Source: https://docs.pawapay.io/v2/api-reference/deposits/initiate-deposit

Example of the RFC3339 formatted timestamp used for deposit creation.

```text
'2020-02-21T17:32:29Z'
```

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

### Refund Response Example

Source: https://docs.pawapay.io/v2/api-reference/refunds

Example of a successful response body returned after initiating a refund.

```json
{
  "refundId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "status": "ACCEPTED",
  "created": "2020-10-19T11:17:01Z"
}
```

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

### Transaction Metadata Examples

Source: https://docs.pawapay.io/v2/api-reference/payment-page/deposit-via-payment-page

Examples of metadata fields and objects for payment requests.

```json
"orderId": "ORD-123456789"
```

```json
true
```

```json
[
  {
    "orderId": "ORD-123456789"
  },
  {
    "customerId": "customer@email.com",
    "isPII": true
  }
]
```

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

### Amount Field Example

Source: https://docs.pawapay.io/v2/api-reference/payment-page/deposit-via-payment-page

Example value for the payment amount field.

```json
'15'
```

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

### Metadata Object Example

Source: https://docs.pawapay.io/v2/api-reference

Example of the metadata array structure for attaching additional context to a payment.

```json
[
  { "orderId": "ORD-123456789" },
  { 
    "customerId": "customer@email.com", 
    "isPII": true 
  }
]
```

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

### Transaction Metadata Examples

Source: https://docs.pawapay.io/v2/api-reference/payouts/initiate-payout

Examples of metadata fields and object structures for transaction requests.

```json
"orderId": "ORD-123456789"
```

```json
true
```

```json
- orderId: ORD-123456789
- customerId: customer@email.com
  isPII: true
```

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

### Define Unknown Failure Response Example

Source: https://docs.pawapay.io/v2/api-reference/toolkit/predict-provider

Example structure for an unknown failure response.

```yaml
'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.
```

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

### Statement ID Schema Example

Source: https://docs.pawapay.io/v2/api-reference/finances/check-statement-status

Example of a valid UUID format for a statement ID.

```text
f4401bd2-1568-4140-bf2d-eb77d2b2b639
```

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

### Refund Not Found Response Example

Source: https://docs.pawapay.io/v2/api-reference/refunds/check-refund-status

Example structure returned when the requested refund ID does not exist in the system.

```yaml
Refund Not Found:
  value:
    status: NOT_FOUND
```

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

### OpenAPI Error Response Examples

Source: https://docs.pawapay.io/v2/api-reference/payouts/initiate-bulk-payout

Examples of JSON error responses for authentication, authorization, and unknown failures.

```yaml
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.
```

```yaml
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.
```

```yaml
examples:
                UNKNOWN_ERROR:
                  value:
                    failureReason:
                      failureCode: UNKNOWN_ERROR
                      failureMessage: Unable to process request due to an unknown problem.
```

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

### OpenAPI Specification for Payout Status

Source: https://docs.pawapay.io/v2/api-reference/payouts/check-payout-status

Defines the GET endpoint for retrieving payout status and includes example response payloads for various transaction states.

```yaml
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/payouts/{payoutId}:
    get:
      tags:
        - payouts
      summary: Check payout status
      operationId: getPayout
      parameters:
        - $ref: '#/components/parameters/PayoutId'
      responses:
        '200':
          description: Request has been processed by PawaPay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutSearchResult'
              examples:
                COMPLETED:
                  value:
                    status: FOUND
                    data:
                      payoutId: 8917c345-4791-4285-a416-62f24b6982db
                      status: COMPLETED
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      clientReferenceId: REF-987654321
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      providerTransactionId: '12356789'
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                ACCEPTED:
                  value:
                    status: FOUND
                    data:
                      payoutId: 8917c345-4791-4285-a416-62f24b6982db
                      status: ACCEPTED
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      clientReferenceId: REF-987654321
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                PROCESSING:
                  value:
                    status: FOUND
                    data:
                      payoutId: 8917c345-4791-4285-a416-62f24b6982db
                      status: PROCESSING
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      clientReferenceId: REF-987654321
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                IN_RECONCILIATION:
                  value:
                    status: FOUND
                    data:
                      payoutId: 8917c345-4791-4285-a416-62f24b6982db
                      status: IN_RECONCILIATION
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      clientReferenceId: REF-987654321
```

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

### OpenAPI Specification for Check Checkout Status

Source: https://docs.pawapay.io/v2/api-reference/checkouts/check-checkout-status

Defines the GET endpoint for retrieving checkout status, including example responses for WAITING_PAYMENT and COMPLETED states.

```yaml
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/checkouts/{checkoutId}:
    get:
      tags:
        - checkouts
      summary: Check checkout status
      operationId: getCheckout
      parameters:
        - $ref: '#/components/parameters/CheckoutId'
      responses:
        '200':
          description: Request has been processed by PawaPay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSearchResult'
              examples:
                WAITING_PAYMENT:
                  value:
                    status: FOUND
                    data:
                      checkoutId: afb57b93-7849-49aa-babb-4c3ccbfe3d79
                      status: WAITING_PAYMENT
                      redirectUrl: >-
                        https://payment.example.com/checkout/afb57b93-7849-49aa-babb-4c3ccbfe3d79
                      created: '2026-03-27T10:30:00Z'
                      countries: []
                      amounts: []
                      depositsHistory: []
                      metadata: {}
                      reason: {}
                      checkoutCode: PPGAFB57B93
                COMPLETED:
                  value:
                    status: FOUND
                    data:
                      checkoutId: afb57b93-7849-49aa-babb-4c3ccbfe3d79
                      status: COMPLETED
                      redirectUrl: >-
                        https://payment.example.com/checkout/afb57b93-7849-49aa-babb-4c3ccbfe3d79
                      returnUrl: https://merchant.example.com/checkout-result
                      returnMethod: INSTANT
                      defaultLanguage: en
                      countries:
                        - ZMB
                      expiresAfter: 60
                      amounts:
                        - country: ZMB
                          currency: ZMW
                          amount: '100'
                      payer:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260973024434'
                          provider: MTN_MOMO_ZMB
                          allowCustomerToOverride: true
                      clientReferenceId: ORDER-123
                      created: '2026-03-27T10:30:00Z'
                      providerTransactionId: PROVIDER-TXN-123
                      depositStatus: COMPLETED
                      deposit:
                        depositId: eac4d2f3-cf36-4a24-a9eb-7014c630f8f0
                        status: COMPLETED
                        created: '2026-03-27T10:35:00Z'
                        providerTransactionId: PROVIDER-TXN-123
                        amount: '100'
                        currency: ZMW
                        country: ZMB
                        payer:
                          type: MMO
                          accountDetails:
                            phoneNumber: '260973024434'
                            provider: MTN_MOMO_ZMB
                        customerMessage: To ACME company
                      depositsHistory:
                        - depositId: eac4d2f3-cf36-4a24-a9eb-7014c630f8f0
                          status: COMPLETED
                          created: '2026-03-27T10:35:00Z'
                          providerTransactionId: PROVIDER-TXN-123
                          amount: '100'
                          currency: ZMW
                          country: ZMB
                          payer:
                            type: MMO
```

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

### OpenAPI Specification for Check Remittance Status

Source: https://docs.pawapay.io/v2/api-reference/remittances/check-remittance-status

Defines the GET endpoint for retrieving remittance details, including various response examples for different transaction statuses.

```yaml
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/remittances/{remittanceId}:
    get:
      tags:
        - remittances
      summary: Check remittance status
      operationId: getRemittance
      parameters:
        - $ref: '#/components/parameters/RemittanceId'
      responses:
        '200':
          description: Request has been processed by PawaPay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemittanceSearchResult'
              examples:
                COMPLETED:
                  value:
                    status: FOUND
                    data:
                      remittanceId: 8917c345-4791-4285-a416-62f24b6982db
                      status: COMPLETED
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      providerTransactionId: '12356789'
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                ACCEPTED:
                  value:
                    status: FOUND
                    data:
                      remittanceId: 8917c345-4791-4285-a416-62f24b6982db
                      status: ACCEPTED
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                PROCESSING:
                  value:
                    status: FOUND
                    data:
                      remittanceId: 8917c345-4791-4285-a416-62f24b6982db
                      status: PROCESSING
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                IN_RECONCILIATION:
                  value:
                    status: FOUND
                    data:
                      remittanceId: 8917c345-4791-4285-a416-62f24b6982db
                      status: IN_RECONCILIATION
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      metadata:
```

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

### Initiate a deposit

Source: https://docs.pawapay.io/v2/api-reference/deposits

Examples for initiating a deposit request across various programming languages.

```curl
curl --request POST \
  --url https://api.sandbox.pawapay.io/v2/deposits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "payer": {
    "type": "MMO",
    "accountDetails": {
      "phoneNumber": "260763456789",
      "provider": "MTN_MOMO_ZMB"
    }
  },
  "amount": "15",
  "currency": "ZMW",
  "preAuthorisationCode": "<string>",
  "clientReferenceId": "INV-123456",
  "customerMessage": "Note of 4 to 22 chars",
  "metadata": [
    {
      "orderId": "ORD-123456789"
    },
    {
      "customerId": "customer@email.com",
      "isPII": true
    }
  ]
}
'
```

```python
import requests  
  
url = "https://api.sandbox.pawapay.io/v2/deposits"  
  
payload = {  
    "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",  
    "payer": {  
        "type": "MMO",  
        "accountDetails": {  
            "phoneNumber": "260763456789",  
            "provider": "MTN_MOMO_ZMB"  
        }  
    },  
    "amount": "15",  
    "currency": "ZMW",  
    "preAuthorisationCode": "<string>",  
    "clientReferenceId": "INV-123456",  
    "customerMessage": "Note of 4 to 22 chars",  
    "metadata": [  
        { "orderId": "ORD-123456789" },  
        {  
            "customerId": "customer@email.com",  
            "isPII": True  
        }  
    ]  
}  
headers = {  
    "Authorization": "Bearer <token>",  
    "Content-Type": "application/json"  
}  
  
response = requests.post(url, json=payload, headers=headers)  
  
print(response.text)
```

```javascript
const options = {  
  method: 'POST',  
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},  
  body: JSON.stringify({  
    depositId: 'f4401bd2-1568-4140-bf2d-eb77d2b2b639',  
    payer: {  
      type: 'MMO',  
      accountDetails: {phoneNumber: '260763456789', provider: 'MTN_MOMO_ZMB'}  
    },  
    amount: '15',  
    currency: 'ZMW',  
    preAuthorisationCode: '<string>',  
    clientReferenceId: 'INV-123456',  
    customerMessage: 'Note of 4 to 22 chars',  
    metadata: [{orderId: 'ORD-123456789'}, {customerId: 'customer@email.com', isPII: true}]  
  })  
};  
  
fetch('https://api.sandbox.pawapay.io/v2/deposits', options)  
  .then(res => res.json())  
  .then(res => console.log(res))  
  .catch(err => console.error(err));
```

```php
<?php  
  
$curl = curl_init();  
  
curl_setopt_array($curl, [  
  CURLOPT_URL => "https://api.sandbox.pawapay.io/v2/deposits",  
  CURLOPT_RETURNTRANSFER => true,  
  CURLOPT_ENCODING => "",  
  CURLOPT_MAXREDIRS => 10,  
  CURLOPT_TIMEOUT => 30,  
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,  
  CURLOPT_CUSTOMREQUEST => "POST",  
  CURLOPT_POSTFIELDS => json_encode([  
    'depositId' => 'f4401bd2-1568-4140-bf2d-eb77d2b2b639',  
    'payer' => [  
        'type' => 'MMO',  
        'accountDetails' => [  
                'phoneNumber' => '260763456789',  
                'provider' => 'MTN_MOMO_ZMB'  
        ]  
    ],  
    'amount' => '15',  
    'currency' => 'ZMW',  
    'preAuthorisationCode' => '<string>',  
    'clientReferenceId' => 'INV-123456',  
    'customerMessage' => 'Note of 4 to 22 chars',  
    'metadata' => [  
        [  
                'orderId' => 'ORD-123456789'  
        ],  
        [  
                'customerId' => 'customer@email.com',  
                'isPII' => true  
        ]  
    ]  
  ]),  
  CURLOPT_HTTPHEADER => [  
    "Authorization: Bearer <token>",  
    "Content-Type: application/json"  
  ],  
]);  
  
$response = curl_exec($curl);  
$err = curl_error($curl);  
  
curl_close($curl);  
  
if ($err) {  
  echo "cURL Error #:" . $err;  
} else {  
  echo $response;  
}
```

```go
package main  
  
import (  
	"fmt"  
	"strings"  
	"net/http"  
	"io"  
)  
  
func main() {  
  
	url := "https://api.sandbox.pawapay.io/v2/deposits"  
  
payload := strings.NewReader("{\n  \"depositId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"payer\": {\n    \"type\": \"MMO\",\n    \"accountDetails\": {\n      \"phoneNumber\": \"260763456789\",\n      \"provider\": \"MTN_MOMO_ZMB\"\n    }\n  },\n  \"amount\": \"15\",\n  \"currency\": \"ZMW\",\n  \"preAuthorisationCode\": \"<string>\",\n  \"clientReferenceId\": \"INV-123456\",\n  \"customerMessage\": \"Note of 4 to 22 chars\",\n  \"metadata\": [\n    {\n      \"orderId\": \"ORD-123456789\"\n    },\n    {\n      \"customerId\": \"customer@email.com\",\n      \"isPII\": true\n    }\n  ]\n}")  
  
	req, _ := http.NewRequest("POST", url, payload)  
  
	req.Header.Add("Authorization", "Bearer <token>")  
	req.Header.Add("Content-Type", "application/json")  
  
	res, _ := http.DefaultClient.Do(req)  
  
	defer res.Body.Close()  
	body, _ := io.ReadAll(res.Body)  
  
	fmt.Println(string(body))  
  
}
```

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

### Initiate Payout Request

Source: https://docs.pawapay.io/v2/api-reference/payouts

Examples of how to initiate a payout request across different programming languages and tools.

```java
HttpResponse<String> response = Unirest.post("https://api.sandbox.pawapay.io/v2/payouts")  
  .header("Authorization", "Bearer <token>")  
  .header("Content-Type", "application/json")  
  .body("{\n  \"payoutId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"recipient\": {\n    \"type\": \"MMO\",\n    \"accountDetails\": {\n      \"phoneNumber\": \"260763456789\",\n      \"provider\": \"MTN_MOMO_ZMB\"\n    }\n  },\n  \"amount\": \"15\",\n  \"currency\": \"ZMW\",\n  \"clientReferenceId\": \"INV-123456\",\n  \"customerMessage\": \"Note of 4 to 22 chars\",\n  \"metadata\": [\n    {\n      \"orderId\": \"ORD-123456789\"\n    },\n    {\n      \"customerId\": \"customer@email.com\",\n      \"isPII\": true\n    }\n  ]\n}")  
  .asString();
```

```ruby
require 'uri'  
require 'net/http'  
  
url = URI("https://api.sandbox.pawapay.io/v2/payouts")  
  
http = Net::HTTP.new(url.host, url.port)  
http.use_ssl = true  
  
request = Net::HTTP::Post.new(url)  
request["Authorization"] = 'Bearer <token>'  
request["Content-Type"] = 'application/json'  
request.body = "{\n  \"payoutId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"recipient\": {\n    \"type\": \"MMO\",\n    \"accountDetails\": {\n      \"phoneNumber\": \"260763456789\",\n      \"provider\": \"MTN_MOMO_ZMB\"\n    }\n  },\n  \"amount\": \"15\",\n  \"currency\": \"ZMW\",\n  \"clientReferenceId\": \"INV-123456\",\n  \"customerMessage\": \"Note of 4 to 22 chars\",\n  \"metadata\": [\n    {\n      \"orderId\": \"ORD-123456789\"\n    },\n    {\n      \"customerId\": \"customer@email.com\",\n      \"isPII\": true\n    }\n  ]\n}"  
  
response = http.request(request)  
puts response.read_body
```

```bash
curl --request POST \
  --url https://api.sandbox.pawapay.io/v2/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "recipient": {
    "type": "MMO",
    "accountDetails": {
      "phoneNumber": "260763456789",
      "provider": "MTN_MOMO_ZMB"
    }
  },
  "amount": "15",
  "currency": "ZMW",
  "clientReferenceId": "INV-123456",
  "customerMessage": "Note of 4 to 22 chars",
  "metadata": [
    {
      "orderId": "ORD-123456789"
    },
    {
      "customerId": "customer@email.com",
      "isPII": true
    }
  ]
}
'
```

```python
import requests  
  
url = "https://api.sandbox.pawapay.io/v2/payouts"  
  
payload = {  
    "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",  
    "recipient": {  
        "type": "MMO",  
        "accountDetails": {  
            "phoneNumber": "260763456789",  
            "provider": "MTN_MOMO_ZMB"  
        }  
    },  
    "amount": "15",  
    "currency": "ZMW",  
    "clientReferenceId": "INV-123456",  
    "customerMessage": "Note of 4 to 22 chars",  
    "metadata": [  
        { "orderId": "ORD-123456789" },  
        {  
            "customerId": "customer@email.com",  
            "isPII": True  
        }  
    ]  
}  
headers = {  
    "Authorization": "Bearer <token>",  
    "Content-Type": "application/json"  
}  
  
response = requests.post(url, json=payload, headers=headers)  
  
print(response.text)
```

```javascript
const options = {  
  method: 'POST',  
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},  
  body: JSON.stringify({  
    payoutId: 'f4401bd2-1568-4140-bf2d-eb77d2b2b639',  
    recipient: {  
      type: 'MMO',  
      accountDetails: {phoneNumber: '260763456789', provider: 'MTN_MOMO_ZMB'}  
    },  
    amount: '15',  
    currency: 'ZMW',  
    clientReferenceId: 'INV-123456',  
    customerMessage: 'Note of 4 to 22 chars',  
    metadata: [{orderId: 'ORD-123456789'}, {customerId: 'customer@email.com', isPII: true}]  
  })  
};  
  
fetch('https://api.sandbox.pawapay.io/v2/payouts', options)  
  .then(res => res.json())  
  .then(res => console.log(res))  
  .catch(err => console.error(err));
```

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

### OpenAPI definition for checking refund status

Source: https://docs.pawapay.io/v2/api-reference/refunds/check-refund-status

Defines the GET endpoint for retrieving refund details, including various response examples for different refund states.

```yaml
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/refunds/{refundId}:
    get:
      tags:
        - refunds
      summary: Check refund status
      operationId: getRefund
      parameters:
        - $ref: '#/components/parameters/RefundId'
      responses:
        '200':
          description: Request has been processed by PawaPay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundSearchResult'
              examples:
                COMPLETED:
                  value:
                    status: FOUND
                    data:
                      refundId: 8917c345-4791-4285-a416-62f24b6982db
                      status: COMPLETED
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      clientReferenceId: REF-987654321
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      providerTransactionId: '12356789'
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                ACCEPTED:
                  value:
                    status: FOUND
                    data:
                      refundId: 8917c345-4791-4285-a416-62f24b6982db
                      status: ACCEPTED
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      created: '2020-10-19T08:17:01Z'
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      clientReferenceId: REF-987654321
                      customerMessage: From ACME company
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                PROCESSING:
                  value:
                    status: FOUND
                    data:
                      refundId: 8917c345-4791-4285-a416-62f24b6982db
                      status: PROCESSING
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      clientReferenceId: REF-987654321
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                IN_RECONCILIATION:
                  value:
                    status: FOUND
                    data:
                      refundId: 8917c345-4791-4285-a416-62f24b6982db
                      status: IN_RECONCILIATION
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      clientReferenceId: REF-987654321
```
Tokens:
Raw