> 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/nequi.md).

# Nequi

### Overview

Nequi is a digital wallet payment method available in Colombia. Through Direct API integration, merchants can support either or both of the following payment flows:

| Payment flow | `auth_type` | Customer experience                                                                                                                                    |
| ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| QR Code      | `QR`        | Pagsmile returns a QR payload. The merchant displays it as a QR code for the customer to scan and pay with Nequi.                                      |
| Push Payment | `PROMPT`    | A payment request is sent to the Nequi account associated with the customer's phone number. The customer opens the Nequi app and approves the payment. |

This page describes the Direct API integration using `POST /trade/pay`. For a hosted Pagsmile Checkout integration, use `POST /trade/create`; the customer selects the Nequi payment flow on the Checkout page, so the merchant does not pass `auth_type` in the Create Checkout request.

{% hint style="warning" %}
The synchronous response confirms that the payment order was created. Use the asynchronous notification sent to `notify_url` as the final payment result.
{% endhint %}

### Submit a Payin by Nequi

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

This endpoint allows you to submit a Nequi payin in Colombia through Direct API integration.

#### Headers

| Name          | Type   | Required | Description                                                                         |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| Content-Type  | string | Yes      | `application/json; charset=UTF-8`                                                   |
| Authorization | string | Yes      | Basic authentication credential generated by Base64-encoding `app_id:security_key`. |

#### Request Body

| Name              | Type   | Required    | Constraints                                                                 | Description                                                                      |
| ----------------- | ------ | ----------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `app_id`          | string | Yes         | Use the App ID assigned by Pagsmile.                                        | Merchant application ID.                                                         |
| `timestamp`       | string | Yes         | Format: `yyyy-MM-dd HH:mm:ss`.                                              | Request time.                                                                    |
| `out_trade_no`    | string | Yes         | Maximum length: 64 characters. Must be unique for the merchant application. | Merchant order number.                                                           |
| `method`          | string | Yes         | Fixed value: `Nequi`.                                                       | Payment method.                                                                  |
| `order_amount`    | string | Yes         | Amount in COP. Supports up to two decimal places.                           | Payment amount.                                                                  |
| `order_currency`  | string | Yes         | Fixed value: `COP`.                                                         | Payment currency.                                                                |
| `subject`         | string | Yes         | Maximum length: 128 characters.                                             | Payment reason or order title.                                                   |
| `content`         | string | No          | Maximum length: 255 characters.                                             | Payment or order details.                                                        |
| `trade_type`      | string | Yes         | Fixed value: `API`.                                                         | Direct API integration type.                                                     |
| `notify_url`      | string | Yes         | Must begin with `http://` or `https://`.                                    | URL to which Pagsmile sends the asynchronous payment notification.               |
| `return_url`      | string | No          | —                                                                           | URL to which the customer is redirected after the payment flow, when applicable. |
| `buyer_id`        | string | Yes         | Maximum length: 128 characters.                                             | Customer ID in the merchant's system.                                            |
| `timeout_express` | string | No          | For example: `1c`.                                                          | Payment order expiration period.                                                 |
| `auth_type`       | string | Yes         | One of `QR` or `PROMPT`.                                                    | Nequi payment flow.                                                              |
| `customer`        | object | Conditional | Required when `auth_type` is `PROMPT`.                                      | Customer information.                                                            |
| `customer.phone`  | string | Conditional | Required when `auth_type` is `PROMPT`.                                      | Phone number associated with the customer's Nequi account.                       |

### QR Code Payment

Set `auth_type` to `QR`. The response contains `qr_code`, which is the QR payload. Render this value as a QR code and display it to the customer.

#### Request Sample

```json
{
  "app_id": "163***05",
  "timestamp": "2026-10-20 13:18:10",
  "out_trade_no": "out_t***66",
  "method": "Nequi",
  "order_amount": "2000",
  "order_currency": "COP",
  "subject": "trade pay test",
  "content": "trade pay test content",
  "trade_type": "API",
  "notify_url": "https://merchant.example.com/payment/notify",
  "return_url": "https://merchant.example.com/payment/result",
  "buyer_id": "glby",
  "timeout_express": "1c",
  "auth_type": "QR"
}
```

#### Response Sample

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "NERK***D9FD",
  "trade_no": "2026***07",
  "out_trade_no": "out_t***66",
  "web_url": "",
  "pay_url": "https://checkout-test.pagsmile.com/checkout?prepay_id=NERK***D9FD",
  "trade_status": "PROCESSING",
  "qr_code": "00020***WlUSuSFk4k",
  "wallet_url": "https://checkout-test.pagsmile.com/checkout?prepay_id=NERK***D9FD"
}
```

### Push Payment

Set `auth_type` to `PROMPT` and provide `customer.phone`. A payment request is sent to the associated Nequi account for the customer to approve in the Nequi app.

#### Request Sample

```json
{
  "app_id": "163***05",
  "timestamp": "2026-10-20 13:18:10",
  "out_trade_no": "out_t***75",
  "method": "Nequi",
  "order_amount": "2000",
  "order_currency": "COP",
  "subject": "trade pay test",
  "content": "trade pay test content",
  "trade_type": "API",
  "notify_url": "https://merchant.example.com/payment/notify",
  "return_url": "https://merchant.example.com/payment/result",
  "buyer_id": "glby",
  "timeout_express": "1c",
  "auth_type": "PROMPT",
  "customer": {
    "phone": "573***0"
  }
}
```

#### Response Sample

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "cW***B864",
  "trade_no": "2026***09",
  "out_trade_no": "out_t***75",
  "web_url": "",
  "pay_url": "https://checkout-test.pagsmile.com/checkout?prepay_id=cW***B864",
  "trade_status": "PROCESSING",
  "wallet_url": "https://checkout-test.pagsmile.com/checkout?prepay_id=cW***B864"
}
```
