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

# Virtual Account

This section describes how to create and query a Virtual Account and receive payment notifications for Colombia Virtual Account payments.

Colombia Virtual Account payments use `Bre-B` as the payment method.

The Virtual Account is created before the payer initiates a transfer. Creating the Virtual Account does not create a fixed-amount payment order. After funds are transferred to the assigned `account_number`, Pagsmile creates the Payin transaction and sends an asynchronous notification to the merchant's `notify_url`.

#### Create Virtual Account

Use this endpoint to create a Virtual Account for Colombia.

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

**Request Body**

Only the required request parameters are listed below.

<table><thead><tr><th width="220">Parameter</th><th width="100">Type</th><th width="110">Required</th><th>Constraints</th><th>Description</th></tr></thead><tbody><tr><td><code>app_id</code></td><td>string</td><td>Required</td><td>Maximum length: 32 characters.</td><td>The merchant application ID assigned by Pagsmile.</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Required</td><td>Format: <code>yyyy-MM-dd HH:mm:ss</code>; maximum length: 19 characters.</td><td>Request timestamp.</td></tr><tr><td><code>notify_url</code></td><td>string</td><td>Required</td><td>Must be a valid, publicly accessible URL.</td><td>The URL that receives Virtual Account payment notifications.</td></tr><tr><td><code>method</code></td><td>string</td><td>Required</td><td>Fixed value: <code>Bre-B</code>.</td><td>Payment method.</td></tr><tr><td><code>region</code></td><td>string</td><td>Required</td><td>Fixed value: <code>COL</code>.</td><td>Country or region code.</td></tr><tr><td><code>customer</code></td><td>object</td><td>Required</td><td>Must contain <code>customer.buyer_id</code>.</td><td>Customer information.</td></tr><tr><td><code>customer.buyer_id</code></td><td>string</td><td>Required</td><td>Maximum length: 128 characters.</td><td>Merchant-side user ID.</td></tr></tbody></table>

**Request Sample**

```json
{
  "app_id": "16***05",
  "timestamp": "2026-08-24 15:30:00",
  "notify_url": "https://merchant.example.com/pagsmile/notify",
  "method": "Bre-B",
  "region": "COL",
  "customer": {
    "buyer_id": "colombia-va-test-001"
  }
}
```

**Response Sample**

```json
{
  "code": "10000",
  "msg": "Success",
  "account_id": "CD***RH",
  "account_number": "@VA***NRH",
  "buyer_id": "colombia-va-test-001",
  "status": "ACTIVE",
  "notify_url": "https://merchant.example.com/pagsmile/notify",
  "method": "Bre-B"
}
```

Save the returned `account_id` and `account_number`. The payer transfers funds to the `account_number` to complete a payment.

#### Query Virtual Account

Use this endpoint to query the Virtual Account information and status.

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

**Request Body**

<table><thead><tr><th width="180">Parameter</th><th width="100">Type</th><th width="110">Required</th><th>Constraints</th><th>Description</th></tr></thead><tbody><tr><td><code>app_id</code></td><td>string</td><td>Required</td><td>Maximum length: 32 characters.</td><td>The merchant application ID assigned by Pagsmile.</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Required</td><td>Format: <code>yyyy-MM-dd HH:mm:ss</code>; maximum length: 19 characters.</td><td>Request timestamp.</td></tr><tr><td><code>account_id</code></td><td>string</td><td>Required</td><td>Maximum length: 64 characters.</td><td>The Virtual Account ID returned by the Create Virtual Account API.</td></tr></tbody></table>

**Request Sample**

```json
{
  "app_id": "16***05",
  "timestamp": "2026-08-24 15:35:00",
  "account_id": "CD***RH"
}
```

**Response Sample**

```json
{
  "code": "10000",
  "msg": "Success",
  "account_id": "CD***RH",
  "account_number": "@VA***NRH",
  "buyer_id": "colombia-va-test-001",
  "status": "ACTIVE",
  "notify_url": "https://merchant.example.com/pagsmile/notify",
  "method": "Bre-B"
}
```

{% hint style="info" %}
The Query Virtual Account API returns the Virtual Account information and status. It does not return the result of an incoming transfer. Use the asynchronous notification as the final payment result.
{% endhint %}

#### Notification

After the payer transfers funds to the Virtual Account, Pagsmile sends an asynchronous notification to the merchant's `notify_url`.

**Notification Body**

<table><thead><tr><th width="300">Parameter</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>amount</code></td><td>string</td><td>Payment amount received.</td></tr><tr><td><code>out_trade_no</code></td><td>string</td><td>Pagsmile-generated transaction reference for the incoming transfer.</td></tr><tr><td><code>method</code></td><td>string</td><td>Payment method. Fixed value: <code>Bre-B</code>.</td></tr><tr><td><code>trade_status</code></td><td>string</td><td>Transaction status. Value: <code>SUCCESS</code>.</td></tr><tr><td><code>trade_no</code></td><td>string</td><td>Pagsmile transaction number.</td></tr><tr><td><code>currency</code></td><td>string</td><td>Payment currency. Fixed value: <code>COP</code>.</td></tr><tr><td><code>app_id</code></td><td>string</td><td>The merchant application ID assigned by Pagsmile.</td></tr><tr><td><code>user.buyer_id</code></td><td>string</td><td>Merchant-side user ID used when creating the Virtual Account.</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Unix timestamp in seconds indicating when the notification was generated.</td></tr><tr><td><code>transfer_account.account_id</code></td><td>string</td><td>Virtual Account ID.</td></tr><tr><td><code>transfer_account.account_number</code></td><td>string</td><td>Virtual Account number.</td></tr></tbody></table>

**Notification Sample**

#### Notification

After the payer transfers funds to the Virtual Account, Pagsmile sends an asynchronous notification to the merchant's `notify_url`.

**Notification Body**

<table><thead><tr><th width="300">Parameter</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>amount</code></td><td>string</td><td>Payment amount received.</td></tr><tr><td><code>out_trade_no</code></td><td>string</td><td>Pagsmile-generated transaction reference for the incoming transfer.</td></tr><tr><td><code>method</code></td><td>string</td><td>Payment method. Fixed value: <code>Bre-B</code>.</td></tr><tr><td><code>trade_status</code></td><td>string</td><td>Transaction status. Value: <code>SUCCESS</code>.</td></tr><tr><td><code>trade_no</code></td><td>string</td><td>Pagsmile transaction number.</td></tr><tr><td><code>currency</code></td><td>string</td><td>Payment currency. Fixed value: <code>COP</code>.</td></tr><tr><td><code>app_id</code></td><td>string</td><td>The merchant application ID assigned by Pagsmile.</td></tr><tr><td><code>user.buyer_id</code></td><td>string</td><td>Merchant-side user ID used when creating the Virtual Account.</td></tr><tr><td><code>user.ip</code></td><td>string</td><td>IP address stored with the user information.</td></tr><tr><td><code>payer.account.number</code></td><td>string</td><td>Payer bank account number.</td></tr><tr><td><code>payer.account.type</code></td><td>string</td><td>Payer account type reported by the provider. Example: <code>DORD</code>.</td></tr><tr><td><code>payer.bank.bank_id</code></td><td>string</td><td>Identifier of the payer's bank.</td></tr><tr><td><code>payer.bank.bank_name</code></td><td>string</td><td>Name of the payer's bank.</td></tr><tr><td><code>payer.identification.number</code></td><td>string</td><td>Payer identification number.</td></tr><tr><td><code>payer.identification.type</code></td><td>string</td><td>Payer identification type. Example: <code>NIT</code>.</td></tr><tr><td><code>card</code></td><td>object</td><td>Card information. This object is empty for a <code>Bre-B</code> bank transfer notification.</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Unix timestamp in seconds indicating when the notification was generated.</td></tr><tr><td><code>transfer_account.account_id</code></td><td>string</td><td>Virtual Account ID.</td></tr><tr><td><code>transfer_account.account_number</code></td><td>string</td><td>Virtual Account number.</td></tr></tbody></table>

**Notification Sample**

```json
{
  "amount": "1000.00",
  "out_trade_no": "90***1d",
  "method": "Bre-B",
  "trade_status": "SUCCESS",
  "trade_no": "202***63",
  "currency": "COP",
  "app_id": "163***05",
  "user": {
    "buyer_id": "24***3",
    "ip": "0.0.0.0"
  },
  "payer": {
    "account": {
      "number": "63***6",
      "type": "DORD"
    },
    "bank": {
      "bank_id": "9**5",
      "bank_name": "Kamin"
    },
    "identification": {
      "number": "9**0",
      "type": "NIT"
    }
  },
  "card": {},
  "timestamp": "1785470128",
  "transfer_account": {
    "account_id": "C***H",
    "account_number": "@VA***H"
  }
}
```

Use the asynchronous notification as the final payment result. The merchant callback endpoint must return HTTP status `200` with one of the following response bodies:

```
success
```

or

```json
{"result":"success"}
```

Pagsmile includes the following header in the notification:

```
Pagsmile-Signature: t=<unix_timestamp>,v2=<hmac_sha256>
```

Calculate the expected signature by applying HMAC-SHA256 to the original, unmodified Request Body using the merchant SecretKey. Do not parse and reserialize the JSON before signature verification. For more information, see [Notification](https://docs.pagsmile.com/payin/notification).