> 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/peru/virtual-account.md). # Virtual Account This section describes how to create a Virtual Account, query the Virtual Account status, and receive payment notifications for Peru Virtual Account payments. Peru Virtual Account payments use `VABankTransfer` as the payment method and `PEN` as the payment currency. For Peru Virtual Account payments, the Virtual Account is created first. After the payer transfers funds to the assigned `account_number`, Pagsmile creates the Payin transaction and sends an asynchronous notification to the merchant's `notify_url`. {% hint style="info" %} Each incoming transfer must be between `1.00` and `10000.00` PEN. Payments are processed in real time. {% endhint %} {% hint style="warning" %} Peru Virtual Account payments do not support refunds. {% endhint %} ### Create Virtual Account Use this endpoint to create a Virtual Account for Peru. POST `https://gateway-test.pagsmile.com/virtual-account/create` #### Request Body
ParameterTypeRequiredConstraintsDescription
app_idstringRequiredMaximum length: 32 characters.The merchant application ID assigned by Pagsmile.
timestampstringRequiredFormat: yyyy-MM-dd HH:mm:ss; maximum length: 19 characters.Request timestamp.
notify_urlstringRequiredMust be a valid, publicly accessible URL.The URL that receives Virtual Account payment notifications.
regionstringRequiredFixed value: PER.Country or region code.
methodstringRequiredFixed value: VABankTransfer.Payment method.
customer.usernamestringRequiredMust be a non-empty full name.Customer's full name.
customer.buyer_idstringOptionalMaximum length: 128 characters.Merchant-side customer ID associated with the Virtual Account.
customer.emailstringOptionalMaximum length: 64 characters.Customer's email address.
customer.phonestringOptional—Customer's phone number.
customer.identify.typestringOptionalExample: DNI. If provided, submit it together with customer.identify.number.Customer's identification type.
customer.identify.numberstringOptionalMaximum length: 64 characters. If provided, submit it together with customer.identify.type.Customer's identification number.
#### Request Sample ```json { "app_id": "163****4108", "timestamp": "2025-03-20 11:11:11", "notify_url": "https://your-notify-url.com", "region": "PER", "customer": { "username": "Test Test", "buyer_id": "0002", "email": "te***@test.com", "phone": "79***609", "identify": { "type": "DNI", "number": "74***186" } }, "method": "VABankTransfer" } ``` #### Response Sample ```json { "code": "10000", "msg": "Success", "account_id": "QD***TUN", "account_number": "921****2041", "status": "ACTIVE", "notify_url": "https://your-notify-url.com", "method": "VABankTransfer" } ``` After the Virtual Account is created successfully, save the returned `account_id` and provide the `account_number` to the payer to complete the bank transfer. ### Query Virtual Account Use this endpoint to query the Virtual Account information and status. POST `https://gateway-test.pagsmile.com/virtual-account/query` #### Request Body | Parameter | Type | Required | Constraints | Description | | ------------ | ------ | -------- | ------------------------------------------------------------- | ------------------------------------------------------------------ | | `app_id` | string | Required | Maximum length: 32 characters. | The merchant application ID assigned by Pagsmile. | | `timestamp` | string | Required | Format: `yyyy-MM-dd HH:mm:ss`; maximum length: 19 characters. | Request timestamp. | | `account_id` | string | Required | Maximum length: 64 characters. | The Virtual Account ID returned by the Create Virtual Account API. | #### Request Sample ```json { "app_id": "163***108", "timestamp": "2025-03-20 11:11:11", "account_id": "TCA***V78" } ``` #### Response Sample ```json { "code": "10000", "msg": "Success", "account_id": "TCA***78", "account_number": "921***044", "buyer_id": "00***01", "status": "ACTIVE", "notify_url": "https://your-notify-url.com", "method": "VABankTransfer" } ``` 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. ### Notification After the payer transfers funds to the Virtual Account, Pagsmile sends an asynchronous notification to the merchant's `notify_url`. #### Notification Body | Parameter | Type | Description | | --------------------------------- | ------ | ------------------------------------------------------------------------------------------------- | | `amount` | string | Payment amount received. | | `out_trade_no` | string | Pagsmile-generated transaction reference for the incoming transfer. | | `method` | string | Payment method. Fixed value: `VABankTransfer`. | | `trade_status` | string | Transaction status. Example: `SUCCESS`. | | `trade_no` | string | Pagsmile transaction number. | | `currency` | string | Payment currency. Fixed value: `PEN`. | | `app_id` | string | The merchant application ID assigned by Pagsmile. | | `user.buyer_id` | string | Merchant-side user ID associated with the Virtual Account, when available. | | `user.email` | string | Customer email address, when available. | | `user.identification.number` | string | Customer identification number, when available. | | `user.identification.type` | string | Customer identification type, when available. Example: `DNI`. | | `user.identify.number` | string | Customer identification number in the legacy identification object, when available. | | `user.identify.type` | string | Customer identification type in the legacy identification object, when available. Example: `DNI`. | | `user.ip` | string | IP address stored with the customer information. | | `user.phone` | string | Customer phone number, when available. | | `payer.account.number` | string | Payer account number reported by the payment provider. | | `payer.account.type` | string | Payer account type reported by the payment provider. This value may be empty. | | `payer.identification.number` | string | Payer identification number. | | `payer.identification.type` | string | Payer identification type. Example: `DNI`. | | `payer.username` | string | Payer's full name. | | `timestamp` | string | Unix timestamp in seconds indicating when the notification was generated. | | `transfer_account.account_id` | string | Virtual Account ID. | | `transfer_account.account_number` | string | Virtual Account number. | #### Notification Sample ```json { "amount": "1.00", "out_trade_no": "393***396", "method": "VABankTransfer", "trade_status": "SUCCESS", "trade_no": "202***063", "currency": "PEN", "app_id": "163***108", "user": { "buyer_id": "00***02", "email": "te***@test.com", "identification": { "number": "74***185", "type": "DNI" }, "identify": { "number": "74***185", "type": "DNI" }, "ip": "0.0.0.0", "phone": "79***609" }, "payer": { "account": { "number": "002***618", "type": "" }, "identification": { "number": "47***535", "type": "DNI" }, "username": "LI***IA" }, "timestamp": "1774539970", "transfer_account": { "account_id": "ULC***0JI", "account_number": "921***044" } } ``` #### Notification Header Sample ```json { "Pagsmile-Signature": "t=1774539970,v2=37c***2bf" } ``` Use the asynchronous notification as the final transaction result. The merchant callback endpoint must return HTTP status `200` with the following JSON response body: ```json { "result": "success" } ``` Calculate the expected `v2` signature by applying HMAC-SHA256 to the original, unmodified notification body using the merchant SecretKey. Do not parse and reserialize the JSON before signature verification. For more information, see [Notification](https://docs.pagsmile.com/reference/payin/notification).