> 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/payin/submit-a-payin/colombia/wallet.md).

# Wallet

How to use Wallet to submit a payin in Colombia.

### Payin by Wallet

<mark style="color:green;">`POST`</mark> `https://gateway-test.pagsmile.com/trade/pay`

This endpoint allows you to submit a payin by Wallet in Colombia.

**Headers**

| Name                                            | Type   | Description                                                                   |
| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | string | `application/json; charset=UTF-8`                                             |
| Authorization<mark style="color:red;">\*</mark> | string | Basic authentication using the Base64-encoded value of `app_id:security_key`. |

**Request Body**

{% hint style="info" %}
The `beneficiary` object and all fields within it are optional for `Dale`, `Daviplata`, `Movii`, `Nequi`, and `Rappipay`, and are **not** required for `TPaga`.
{% endhint %}

<table><thead><tr><th width="247.4453125">Name</th><th width="125.95703125">Type</th><th>Description</th></tr></thead><tbody><tr><td>app_id<mark style="color:red;">*</mark></td><td>string</td><td><p>App ID assigned to the merchant application at dashboard</p><p>- Non-empty; Max. 32 chars -</p></td></tr><tr><td>method<mark style="color:red;">*</mark></td><td>string</td><td><p>Payment method</p><p>- Fixed value: <code>Wallet</code> -</p></td></tr><tr><td>channel<mark style="color:red;">*</mark></td><td>string</td><td><p>Wallet type</p><p>- <code>TPaga</code>, <code>Dale</code>, <code>Daviplata</code>, <code>Movii</code>, <code>Nequi</code>, <code>Rappipay</code> -</p></td></tr><tr><td>order_currency<mark style="color:red;">*</mark></td><td>string</td><td><p>Payment currency</p><p>- Fixed value: <code>COP</code> (3 chars) -</p></td></tr><tr><td>order_amount<mark style="color:red;">*</mark></td><td>string</td><td><p>Payment amount</p><p>- Integer only (<code>TPaga</code>: 1~2,000,000; <code>Dale</code>, <code>Daviplata</code>, <code>Movii</code>, <code>Nequi</code>, <code>Rappipay</code>: 1,000~10,000,000); check here for limits -</p></td></tr><tr><td>out_trade_no<mark style="color:red;">*</mark></td><td>string</td><td><p>Unique ID given by the merchant in their system</p><p>- Non-blank; Max. 64 chars -</p></td></tr><tr><td>content</td><td>string</td><td><p>Payment reason detail or item detail</p><p>- Optional; Max. 255 chars -</p></td></tr><tr><td>timestamp<mark style="color:red;">*</mark></td><td>string</td><td><p>Request time in <code>yyyy-MM-dd HH:mm:ss</code> format</p><p>- Max. 19 chars -</p></td></tr><tr><td>notify_url<mark style="color:red;">*</mark></td><td>string</td><td><p>Where Pagsmile will send notification to</p><p>- Non-blank; valid HTTP/HTTPS URL -</p></td></tr><tr><td>subject<mark style="color:red;">*</mark></td><td>string</td><td><p>Payment reason or item title</p><p>- Non-blank; Max. 128 chars -</p></td></tr><tr><td>buyer_id<mark style="color:red;">*</mark></td><td>string</td><td><p>Merchant user's ID</p><p>- Non-blank; Max. 128 chars -</p></td></tr><tr><td>customer.name<mark style="color:red;">*</mark></td><td>string</td><td><p>User's full name</p><p>- Required; Max. 64 chars -</p></td></tr><tr><td>customer.email<mark style="color:red;">*</mark></td><td>string</td><td><p>User's email address</p><p>- Required; Max. 64 chars -</p></td></tr><tr><td>customer.phone<mark style="color:red;">*</mark></td><td>string</td><td><p>User's phone number</p><p>- Required; Start with <code>"57"</code> (10-digit local number after country code) -</p></td></tr><tr><td>customer.identify.type<mark style="color:red;">*</mark></td><td>string</td><td><p>User's identification type</p><p>- <code>NIT</code> or <code>CC</code> -</p></td></tr><tr><td>customer.identify.number<mark style="color:red;">*</mark></td><td>string</td><td><p>User's identification number</p><p>- <code>NIT</code>: 10 digits, <code>CC</code>: 6~10 digits (Max. 64 chars) -</p></td></tr><tr><td>website_url</td><td>string</td><td><p>Merchant website URL</p><p>- Optional; Max. 128 chars -</p></td></tr><tr><td>address.zip_code</td><td>string</td><td><p>Zip code</p><p>- Optional; 6 digits -</p></td></tr><tr><td>address.street<mark style="color:red;">*</mark></td><td>string</td><td><p>Street address</p><p>- Required for <code>Dale</code>, <code>Daviplata</code>, <code>Movii</code>, <code>Nequi</code>, <code>Rappipay</code> (Max. 64 chars);<br><strong>Not</strong> required for <code>TPaga</code> -</p></td></tr><tr><td>address.street_number</td><td>string</td><td><p>Street number</p><p>- Optional; string -</p></td></tr><tr><td>address.city</td><td>string</td><td><p>City</p><p>- Optional; string -</p></td></tr><tr><td>address.state</td><td>string</td><td><p>State or department</p><p>- Optional; string -</p></td></tr><tr><td>return_url</td><td>string</td><td><p>Redirect to Merchant's URL when user finished checkout</p><p>- Optional; valid HTTP/HTTPS URL -</p></td></tr><tr><td>beneficiary.entity_type</td><td>string</td><td><p>Beneficiary entity type. Available values: <code>individual</code> or <code>company</code></p><p>- Optional for <code>Dale</code>, <code>Daviplata</code>, <code>Movii</code>, <code>Nequi</code>, <code>Rappipay</code>;<br><strong>Not</strong> required for <code>TPaga</code> -</p></td></tr><tr><td>beneficiary.identification.type</td><td>string</td><td><p>Beneficiary identification type, e.g., <code>NIT</code></p><p>- Optional for <code>Dale</code>, <code>Daviplata</code>, <code>Movii</code>, <code>Nequi</code>, <code>Rappipay</code>;<br><strong>Not</strong> required for <code>TPaga</code> -</p></td></tr><tr><td>beneficiary.identification.number</td><td>string</td><td><p>Beneficiary identification number (Max. 64 chars)</p><p>- Optional for <code>Dale</code>, <code>Daviplata</code>, <code>Movii</code>, <code>Nequi</code>, <code>Rappipay</code>;<br><strong>Not</strong> required for <code>TPaga</code> -</p></td></tr><tr><td>beneficiary.name</td><td>string</td><td><p>Beneficiary's full legal name (non-empty when overriding default beneficiary info)</p><p>- Optional for <code>Dale</code>, <code>Daviplata</code>, <code>Movii</code>, <code>Nequi</code>, <code>Rappipay</code>;<br><strong>Not</strong> required for <code>TPaga</code> -</p></td></tr><tr><td>beneficiary.industry.type</td><td>string</td><td><p>Industry classification system. Available values: <code>CIIU</code>, <code>MCC</code>, <code>CNAE</code>, <code>SCIAN</code>, or <code>GB/T</code></p><p>- Optional for <code>Dale</code>, <code>Daviplata</code>, <code>Movii</code>, <code>Nequi</code>, <code>Rappipay</code>;<br><strong>Not</strong> required for <code>TPaga</code> -</p></td></tr><tr><td>beneficiary.industry.code</td><td>string</td><td><p>Industry code under the classification system specified by <code>beneficiary.industry.type</code>, e.g., <code>4711</code></p><p>- Optional for <code>Dale</code>, <code>Daviplata</code>, <code>Movii</code>, <code>Nequi</code>, <code>Rappipay</code>;<br><strong>Not</strong> required for <code>TPaga</code> -</p></td></tr></tbody></table>

**Request Sample**

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

```json
{
  "app_id": "162************38",
  "out_trade_no": "202610280354004",
  "method": "Wallet",
  "channel": "TPaga",
  "order_amount": "12",
  "order_currency": "COP",
  "subject": "trade pay test",
  "content": "trade pay test content",
  "notify_url": "https://merchant.example.com/callback/success",
  "return_url": "https://merchant.example.com/payment/result",
  "buyer_id": "buyer_0101_0001",
  "timestamp": "2026-10-28 03:54:01",
  "timeout_express": "1c",
  "customer": {
    "identify": {
      "type": "NIT",
      "number": "1234123121"
    },
    "name": "Test User Name",
    "email": "test@pagsmile.com",
    "phone": "57468****068"
  }
}
```

{% endtab %}

{% tab title="Dale / Daviplata / Movii / Nequi / Rappipay" %}

```json
{
  "app_id": "162************38",
  "out_trade_no": "202610280354005",
  "method": "Wallet",
  "channel": "Dale",
  "order_amount": "3000",
  "order_currency": "COP",
  "subject": "trade pay test",
  "content": "trade pay test content",
  "notify_url": "https://merchant.example.com/callback/success",
  "return_url": "https://merchant.example.com/payment/result",
  "buyer_id": "buyer_0101_0001",
  "timestamp": "2026-10-28 03:54:01",
  "timeout_express": "1c",
  "customer": {
    "identify": {
      "type": "NIT",
      "number": "1234123121"
    },
    "name": "Test User Name",
    "email": "test@pagsmile.com",
    "phone": "57468****068"
  },
  "address": {
    "street": "test address wer"
  },
  "beneficiary": {
    "entity_type": "individual",
    "identification": {
      "type": "NIT",
      "number": "900123456"
    },
    "name": "Comercial Ejemplo S.A.S.",
    "industry": {
      "type": "GB/T",
      "code": "4711"
    }
  }
}
```

{% endtab %}
{% endtabs %}

**Response**

{% tabs %}
{% tab title="200 Submit successfully" %}
{% tabs %}
{% tab title="TPaga" %}

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "QVUvcG00ZDl6MFVsWkZsTk1IwRDlTZEdnVThOUGxyeHVnZkROND0=-D161Bae8",
  "trade_no": "22022010110293900083",
  "out_trade_no": "202201010354005",
  "web_url": "",
  "trade_status": "PROCESSING",
  "wallet_url": "https://w.tpaga.co/eyJtIjp7Im8iOiJQUiJ9LCJkIjp7InMiOiJQYWdzbWlsZSIsInBydCI6InByLTJlZmYyMzI4NjgxNDNkNjA5OGVlZGJjNGY1YWQ3NjNmMzMxNjdkZmJiYWNkYTc3ZDUxZTgyMzY4ODg4NWRlZTM0ZDViYzM0NyJ9fQ=="
}
```

{% endtab %}

{% tab title="Dale" %}

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "QVUvcG00ZDl6MFVsWkZsTk1IwRDlTZEdnVThOUGxyeHVnZkROND0=-D161Bae8",
  "trade_no": "22022010110293900083",
  "out_trade_no": "202201010354005",
  "web_url": "",
  "trade_status": "PROCESSING",
  "wallet_url": "https://registro.pse.com.co/PSENF/index.html?enc="
}
```

{% endtab %}

{% tab title="Daviplata" %}

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "QVUvcG00ZDl6MFVsWkZsTk1IwRDlTZEdnVThOUGxyeHVnZkROND0=-D161Bae8",
  "trade_no": "22022010110293900083",
  "out_trade_no": "202201010354005",
  "web_url": "",
  "trade_status": "PROCESSING",
  "wallet_url": "https://registro.pse.com.co/PSENF/index.html?enc="
}
```

{% endtab %}

{% tab title="Movii" %}

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "QVUvcG00ZDl6MFVsWkZsTk1IwRDlTZEdnVThOUGxyeHVnZkROND0=-D161Bae8",
  "trade_no": "22022010110293900083",
  "out_trade_no": "202201010354005",
  "web_url": "",
  "trade_status": "PROCESSING",
  "wallet_url": "https://registro.pse.com.co/PSENF/index.html?enc="
}
```

{% endtab %}

{% tab title="Nequi" %}

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "QVUvcG00ZDl6MFVsWkZsTk1IwRDlTZEdnVThOUGxyeHVnZkROND0=-D161Bae8",
  "trade_no": "22022010110293900083",
  "out_trade_no": "202201010354005",
  "web_url": "",
  "trade_status": "PROCESSING",
  "wallet_url": "https://registro.pse.com.co/PSENF/index.html?enc="
}
```

{% endtab %}

{% tab title="Rappipay" %}

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "QVUvcG00ZDl6MFVsWkZsTk1IwRDlTZEdnVThOUGxyeHVnZkROND0=-D161Bae8",
  "trade_no": "22022010110293900083",
  "out_trade_no": "202201010354005",
  "web_url": "",
  "trade_status": "PROCESSING",
  "wallet_url": "https://registro.pse.com.co/PSENF/index.html?enc="
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="400 Duplicate out\_trade\_no" %}

```json
{
  "code": "40002",
  "msg": "Business Failed",
  "sub_code": "duplicate-out_trade_no",
  "sub_msg": "out_trade_no is duplicate"
}
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
Use your own `app_id` and generate the corresponding authorization value when testing.
{% endhint %}
