# Payout & Payin

Payout and Payin functions work the same way as off-ramp and on-ramp transactions. They use the same request body structure, except **`transaction_hash`** & **`chain`** are not included in payout/payin requests. See the On-Ramp / Off-Ramp section for more details.

#### Disbursement

This endpoint calls the Pretium payment protocol to verify that the payment has been made and releases the equivalent fiat amount.

| Name            | Type    | Description                                             |
| --------------- | ------- | ------------------------------------------------------- |
| type            | String  | Type of payment, MOBILE, BUY\_GOODS & PAYBILL           |
| shortcode       | String  | Recipient mobile number, till number or  paybill number |
| account\_number | String  | Required if type is PAYBILL                             |
| amount          | Integer | Amount to disburse                                      |
| mobile\_network | String  | Supported mobile network ie Safaricom                   |
| callback\_url   | URL     | URL to receive payment notification                     |

```
POST {{url}}/{{currencyCode}}/disburse
```

{% tabs %}
{% tab title="Request Body" %}

```
{
    "shortcode": "0700123456",
    "amount": "50",
    "type": "MOBILE",
    "mobile_network": "Safaricom", // Airtel (required only when type is MOBILE)
    "callback_url": "https://pretium.africa/b2c/log-test"
}
  

```

{% endtab %}

{% tab title="200 - Success" %}

```
{
    "code": 200,
    "message": "Message",
    "data": {
        "status": "PENDING",
        "transaction_code": "DDM6D",
        "message": "Success! Processing payment..."
    }
}
```

{% endtab %}

{% tab title="400 - Bad Request" %}

```
{
   "code": 400,
   "message": "Failed - Bad Request"
}
```

{% endtab %}
{% endtabs %}

#### Collection

This endpoint calls the Pretium payment protocol to initiate cash collection from the user, confirm receipt via mobile money or bank transfer.

```
POST {{url}}/{{currencyCode}}/collect
```

{% tabs %}
{% tab title="Request Body" %}

```
{
    "shortcode": "0743312265",
    "amount": "20",
    "mobile_network": "Safaricom",//Airtel
    "callback_url": "https://pretium.africa/b2c/log-test"
}
```

{% endtab %}

{% tab title="200 - Success" %}

```
{
    "code": 200,
    "message": "Disburse initiated",
    "data": {
        "status": "PENDING",
        "transaction_code": "TSALX",
        "message": "Success! Processing payment."
    }
}
```

{% endtab %}

{% tab title="400 - Bad Request" %}

```
{
   "code": 400,
   "message": "Failed - Bad Request"
}
```

{% endtab %}
{% endtabs %}

#### Supported Banks

Get a list of all supported banks supported by Pretium APIs. 

```
POST {{url}}/{{currencyCode}}/banks
```

{% tabs %}
{% tab title="200 - Success" %}

```
{
    "code": 200,
    "message": "List of banks",
    "data": [
        {
            "Code": "247247",
            "Name": "Equity Bank"
        },
]
}
```

{% endtab %}

{% tab title="400 - Bad Request" %}

```
{
   "code": 400,
   "message": "Failed - Bad Request"
}
```

{% endtab %}
{% endtabs %}

#### Bank Transfer

This endpoint calls the Pretium payment protocol to verify that the payment has been made and settles the payment to the recipient's bank account.

```
POST {{url}}/{{currencyCode}}/bank-transfer
```

{% tabs %}
{% tab title="Request Body" %}

```
{
    "amount": "500",
    "account_number": "001918181",
    "bank_code": "247247",
}
```

{% endtab %}

{% tab title="200 - Success" %}

```
{
    "code": 200,
    "message": "Message",
    "data": {
        "status": "PENDING",
        "transaction_code": "DDM6D",
        "message": "Success! Processing payment..."
    }
}
```

{% endtab %}

{% tab title="400 - Bad Request" %}

```
{
   "code": 400,
   "message": "Failed - Bad Request"
}
```

{% endtab %}
{% endtabs %}

#### Validation

This endpoint validates a phone number and returns the registered individual's name as provided by Mobile Network Operators (MNOs).

Note: Reliability varies by country, so avoid heavy dependence on this endpoint for phone number validation.

```
POST {{url}}/{{currencyCode}}/validation
```

{% tabs %}
{% tab title="Request Body" %}

```
{
    "shortcode": "0700123456",
     "type": "MOBILE",
     "network": "Safaricom"
}
  

```

{% endtab %}

{% tab title="200 - Success" %}

```
{
    "code": 200,
    "message": "Validation results",
    "data": {
        "status": "COMPLETE",
        "shortcode": "0700123456",
        "public_name": "JOHN DOE"
    }
}

```

{% endtab %}

{% tab title="400 - Bad Request" %}

```
{
   "code": 400,
   "message": "Failed - Bad Request"
}
```

{% endtab %}
{% endtabs %}

#### Status

Fetch a transaction using its transaction code.

```
POST {{url}}/{{currencyCode}}/status
```

{% tabs %}
{% tab title="Request Body" %}

```
{
    "transaction_code": "fg464gggshshkkk"
}
  

```

{% endtab %}

{% tab title="200 - Success" %}

```
{
    "code": 200,
    "message": "Transaction",
    "data": {
        "id": 51215,
        "transaction_code": "045c1753-4e5b-4fa8-997b-ee52b78a96fa",
        "status": "COMPLETE",
        "amount": "20",
        "type": "MOBILE",
        "shortcode": "0700123456",
        "account_number": null,
        "public_name": "JOHN DOE",
        "receipt_number": "TIMCW5AK69",
        "category": "DISBURSEMENT",
        "message": "Transaction processed successfully.",
        "currency_code": "KES",
        "created_at": "2025-09-22T08:08:18.000000Z"
    }
}
```

{% endtab %}

{% tab title="400 - Bad Request" %}

```
{
   "code": 400,
   "message": "Failed - Bad Request"
}
```

{% endtab %}
{% endtabs %}