Skip to content

Create a virtual account

HTTP Request

POST /v1/payments/charges/references

Request Headers
{
  "Content-Type": "application/json",
  "Authorization": "Bearer {{access_token}}",
  "x-api-key": "{{api_key}}"
}
Request Body
{
  "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
  "userInfo": {
    "legalName": "{{TARGET_ACCOUNT_LEGAL_NAME}}",
    "phoneNumber": "{{TARGET_ACCOUNT_PHONE_NUMBER}}"
  },
  "currency": "MXN",
  "country": "MX",
  "paymentMethod": "CLABE_ACCOUNT",
  "callbackUrl": "https://api.client.com/callback/",
  "description": "this is a test references"
}
Content-Type: application/json
{
  "transferStatusCode": 200,
  "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
  "country": "MX",
  "currency": "MXN",
  "createTime": "2023-08-15 20:05:38 GMT-07:00",
  "status": "ACTIVE",
  "description": "this is a test references",
  "callbackUrl": "https://api.client.com/callback/",
  "transferDetails": {
    "clabeAccount": {
      "userInfo": {
        "legalName": "{{TARGET_ACCOUNT_LEGAL_NAME}}",
        "phoneNumber": "{{TARGET_ACCOUNT_PHONE_NUMBER}}"
      },
      "clabeAccountNumber": "706180162569438880"
    }
  }
}

Notification / Callback

Content-Type: application/json
{
  "eventType": "CHARGE_SUCCEEDED",
  "data": {
    "chargeDetails": {
      "transferStatusCode": 200,
      "transferErrorMsg": null,
      "idempotencyKey": "ref_kbO6Zn4cY4vDfBxwJnztxskL3",
      "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
      "paymentMethod": "CLABE_ACCOUNT",
      "amount": 500,
      "finalAmount": 500,
      "currency": "MXN",
      "country": "MX",
      "finalCurrency": "MXN",
      "createTime": "2022-09-01 01:13:01 UTC",
      "finalStatusTime": "2022-09-01 01:13:01 UTC",
      "payer": {
        "name": "{{TARGET_ACCOUNT_NAME}}",
        "phone": "{{TARGET_ACCOUNT_PHONE}}"
      },
      "transferStatus": "SETTLED",
      "callbackUrl": "https://api.client.com/callback/",
      "transferDetails": {
        "clabeAccount": {
          "beneficiaryAccountNumber": "706180162569438880",
          "referenceNumber": "referenceNumber",
          "trackingId": "trackingId",
          "senderName": "senderName",
          "senderAccountNumber": "senderAccountNumber",
          "paymentTime": "2022-09-01 01:13:01 UTC"
        }
      }
    }
  }
}

Request Headers Parameters

Key Value
Authorization "bearer" + " " + {{access_token}}
x-api-key {{api_key}}

Request Body Parameters

Parameter Required Type Description
idempotencyKey String Unique key to ensure idempotent requests. given by the merchant in their system.
country String Country code
currency String The currency code of the transferred fund
paymentMethod String Payment method, enum value as CLABE_ACCOUNT
userInfo JSON User info
description String Description of payment
callbackUrl String URL where Liquido will send notifications associated to changes to this payment. will receive a post request.
User Info Object Parameters
Parameter Required Type Description
legalName String Fullname(Input specification: Only a combination of uppercase and lowercase letters, numbers and spaces is allowed. Spanish and Portuguese letters, and other special characters are not allowed).
phoneNumber String Mobile Phone number.

Response Body Parameters

Parameter Type Description
transferStatusCode Integer Create account status code, 200 create account success
transferErrorMsg String Create account error message if failed
idempotencyKey String Unique key to ensure idempotent requests. given by the merchant in their system
country String Country code
currency String The currency code of the transferred fund
transferDetails JSON Transaction details info
description String Description of payment
callbackUrl String URL where Liquido will send notifications associated to changes to this payment. will receive a post request.
createTime String Payment ticket created time
status String Account status, ACTIVE
TransferDetails Object Parameters
Parameter Type Description
clabeAccount JSON Clabe Account info
ClabeAccount Object Parameters
Parameter Type Description
clabeAccountNumber String Clabe account number of the payment
userInfo JSON User info

Notification / Callback Body Parameters

Parameter Type Description
transferStatusCode Integer Transfer status code, 200 transaction SETTLED
transferErrorMsg String Transfer error message if failed
idempotencyKey String Unique key to ensure idempotent requests
referenceId String Unique key provided by creating reference request
paymentMethod String Payment method, enum value as CLABE_ACCOUNT
amount Long The transfer amount,the minimum settlement granularity of the current currency, such as 100 = 1MXN
finalAmount Long The final amount that is used for creating the charge order. EX: for charge orders with FX conversion, this field represents the converted amount from the original requested amount.
country String Country code
currency String The currency code of the transferred fund
finalCurrency String The currency code of the finalAmount.
createTime String Payment ticket created time
finalStatusTime String Transfer final status update time, final status include SETTLED
payer JSON Payer info
transferStatus String Transfer status, SETTLED
callbackUrl String URL where Liquido will send notifications associated to changes to this payment. will receive a post request.
transferDetails JSON Transaction details info
ClabeAccount Object Parameters
Parameter Type Description
referenceNumber String The reference number of the payment, return blank string if no data
trackingId String The tracking id of the payment, return blank string if no data
senderName String Name of the payer, return blank string if no data
senderAccountNumber String CLABE account number of the payer, return blank string if no data
paymentTime String Actual time pay to virtual accounts, this field maybe blank string due to bank exceptions, resulting in no return
beneficiaryAccountNumber String Beneficiary CLABE account number

Notification Event Type

CHARGE_SUCCEEDED
Back to top