> For the complete documentation index, see [llms.txt](https://docs.pagsmile.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagsmile.com/reference/remittance-api/business/partner/create-topup-order.md).

# Create Topup Order

Creates a top-up order to add funds to a partner balance and records the expected incoming payment details.

#### Endpoint

`POST /remittance/partner/create-topup`

**Sandbox base URL:** `https://rem-api-sandbox.pagsmile.com`\
**Content-Type:** `application/json; charset=UTF-8`

The request uses the standard [Remittance API request envelope](https://docs.pagsmile.com/remittance-api/common). The fields below describe the decrypted `biz_data` object.

{% hint style="info" %}
**Requirement:** `M` = Mandatory, `O` = Optional, and `C` = Conditional. A conditional field is mandatory only when the condition stated in its description applies.
{% endhint %}

{% hint style="warning" %}
Encrypt `biz_data`, encrypt the AES key into `random_key`, and sign the request according to the Common request specification.
{% endhint %}

#### Request body

**Decrypted `biz_data` fields**

| Field                 | Type   | Requirement | Description                                                                                                                                                                                                         |
| --------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order_no`            | string | M           | Merchant-defined order number used to submit, query, and reconcile the top-up order.                                                                                                                                |
| `pay_amount`          | string | M           | Amount debited in the payment currency.                                                                                                                                                                             |
| `pay_currency`        | string | M           | <p>Three-letter ISO 4217 code of the currency debited for the transaction.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/currency">currency</a> for supported values.</p> |
| `topup_currency`      | string | M           | <p>Three-letter ISO 4217 code of the currency credited by the top-up.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/currency">currency</a> for supported values.</p>      |
| `reference`           | string | O           | Merchant-provided reference used to reconcile the top-up order with the merchant's internal records.                                                                                                                |
| `payment.account_no`  | string | O           | Bank or platform account number to which the top-up is credited.                                                                                                                                                    |
| `payment.bank_name`   | string | O           | Name of the financial institution that holds the account.                                                                                                                                                           |
| `payment.arrive_date` | string | O           | Expected date and time when the incoming top-up payment will arrive.                                                                                                                                                |

**Plaintext `biz_data` example**

{% hint style="info" %}
This example includes mandatory fields and representative optional or conditional fields. Submit fields marked `C` only when the condition in the field description applies.
{% endhint %}

```json
{
  "order_no": "ORDER_202607200001",
  "pay_amount": "100.00",
  "pay_currency": "USD",
  "topup_currency": "USD",
  "reference": "Example reference",
  "payment": {
    "account_no": "1234567890",
    "bank_name": "Example Bank",
    "arrive_date": "2026-07-20 10:30:00"
  }
}
```

#### Request example

```bash
curl --request POST \
  --url https://rem-api-sandbox.pagsmile.com/remittance/partner/create-topup \
  --header 'Content-Type: application/json; charset=UTF-8' \
  --data '{
    "partner_id": "<your_partner_id>",
    "app_id": "<your_app_id>",
    "timestamp": "2026-07-20 10:30:00",
    "version": "2.0",
    "language": "en",
    "random_key": "<RSA-encrypted AES key>",
    "request_id": "<globally_unique_request_id>",
    "sign_type": "RSA",
    "biz_data": "<AES-encrypted biz_data>"
  }'
```

{% hint style="info" %}
Use the `partner_id` and `app_id` assigned to your integration. The values above are placeholders.
{% endhint %}

#### Response

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

```json
{
  "code": "10000",
  "msg": "Success",
  "data": {
    "order_id": 100009
  },
  "total": 1,
  "random_key": "abssdddd2wdw==",
  "sign_type": "RSA",
  "app_id": "2017051914172236111"
}
```

{% endtab %}

{% tab title="Invalid signature" %}

```json
{
  "code": "40002",
  "msg": "Business Failed",
  "sub_code": "invalid-signature",
  "sub_msg": "invalid signature"
}
```

{% endtab %}
{% endtabs %}

**Response data fields**

| Field      | Type | Requirement | Description                                       |
| ---------- | ---- | ----------- | ------------------------------------------------- |
| `order_id` | long | O           | Pagsmile-assigned unique identifier of the order. |

#### Related APIs

* [Query Partner Balance](https://docs.pagsmile.com/remittance-api/business/partner/query-partner-balance)
* [Query Partner Transactions](https://docs.pagsmile.com/remittance-api/business/partner/query-partner-transactions)
* [Query Topup Result](https://docs.pagsmile.com/remittance-api/business/partner/query-topup-result)