Virtual Accounts

Introduction

Here we describe the use of Virtual Accounts API, by using it merchants are able to assignee a unique account to their customers so they can make deposit and payments.

The first step in the process is to assign an account to the customer, after the process is completed the customer will be able to receive deposit to the assigned account.

The possible status for a virtual accounts are:

processing: the account is being creared.
complete: the account was created.
error: an error occurred when the account was being created.
deleted: tha account was deleted.

Creating the Account

Flow

API Examples

Auth-Service API

curl --location --request POST 'https://{{baseUrl}}/auth-service/1.1/protocol/openid-connect/token' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username={{username}}' \
--data-urlencode 'password={{password}}'

{
    "access_token": "{{access_token}}",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "{{refresh_token}}",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "{{session_state}}",
    "scope": "profile email"
}

Payment-Methods API

curl --location --request GET 'https://{{baseUrl}}/payment-methods/1.0/paymentmethodtypes?direction=in&country=AR&paymentMethodTypeClass=virtualAccount&paymentMethodTypeStatus=available' \
--header 'X-User-Bearer: {{access_token}}' \' \
--header 'X-User-Bearer: {{access_token}}' \
--header 'x-api-key: {{apikey}}'

[
    {
        "country": "AR",
        "currency": "ARG",
        "directUsage": true,
        "direction": "in",
        "fields": [
            {
                "description": "Tipo de documento",
                "fieldType": "select",
                "isUserField": true,
                "mandatory": true,
                "name": "document_type",
                "regex": ".*",
                "validOptions": [
                    "ruc"
                ]
            },
            {
                "description": "Número de documento",
                "fieldType": "input",
                "isUserField": true,
                "mandatory": true,
                "name": "document_number",
                "regex": ".*",
                "validOptions": []
            },
            {
                "description": "Nombre",
                "fieldType": "input",
                "isUserField": true,
                "mandatory": true,
                "name": "first_name",
                "regex": "^[a-zA-Z ]+$",
                "validOptions": []
            },
            {
                "description": "Apellido",
                "fieldType": "input",
                "isUserField": true,
                "mandatory": true,
                "name": "last_name",
                "regex": "^[a-zA-Z ]+$",
                "validOptions": []
            }
        ],
        "imageURL": null,
        "paymentMethodType": "virtualaccount1in-ars",
        "paymentMethodTypeClass": "virtualAccount",
        "paymentMethodTypeDescription": "Virtual Account 1 ARS",
        "paymentMethodTypePos": [],
        "paymentMethodTypeStatus": "available",
        "protected": false,
        "storable": false,
        "usage": null
    }
]

Virtual Account API

curl --location --request POST 'https://{{baseUrl}}/virtualaccounts/1.0/virtualAccounts
--header 'X-User-Bearer: {{access_token}}' \
--header 'x-api-key: {{apikey}}' \
--data-raw '{
    "paymentMethodTypeId": "virtualaccount1in-ars",
    "paymentMethodReference": "3235383934342D313030302D31313630",
    "virtualAccountKey": "11111111111",
    "data": {
        "first_name": "Gonzalo",
        "last_name": "Zabala",
         "document_type": "ruc",
         "document_number": "11111111111"
    }
}'

{
    "paymentMethodTypeId": "virtualaccount1in-ars",
    "paymentMethodReference": "3235383934342D313030302D31313630",
    "virtualAccountKey": "11111111111",
    "data": {
        "document_number": "11111111111",
        "document_type": "ruc",
        "first_name": "Gonzalo",
        "last_name": "Zabala"
    },
    "requestReference": "1320",
    "status": "processing",
    "requestDate": "2023-03-03T16:52:12Z",
    "callbackURL": "https://callback.test",
    "deletionRequestDate": null
}

Callback

curl -X 'PUT' 'https://callback.test'
-H 'x-timestamp: 2023-04-21T14:48:02.675317Z' 
-H 'x-signature: signature' 
-H 'x-saltlength: slenght' 
-H 'contet-type: application/json' 
-H 'content-length: clength' 
-H 'user-agent: Go-http-client/1.1' 
-d $ '{
   "paymentMethodTypeId":"virtualaccount1in-ars",
   "paymentMethodReference":"3235383934342D313030302D31313630",
   "virtualAccountKey":"11111111111",
   "data":{
      "document_number":"11111111111",
      "document_type":"ruc",
      "first_name":"Gonzalo",
      "last_name":"Zabala"
   },
   "requestReference":"1320",
   "status":"complete",
   "requestDate":"2023-03-03T16:52:12Z",
   "callbackURL":"https://callback.test",
   "virtualAccountNumber":"0000107200016820884568",
   "deletionRequestDate":null
}’

Receive Payments

Flow

API Example

Callback

curl -X 'PUT' 'https://callback.test'
-H 'x-timestamp: 2023-04-21T14:48:02.675317Z' 
-H 'x-signature: signature' 
-H 'x-saltlength: slenght' 
-H 'x-CorrelationID: correlationId'
-H 'contet-type: application/json' 
-H 'content-length: clength' 
-H 'user-agent: Go-http-client/1.1' 
-d $ '{
  "amount": "50.00000000",
  "conciliationOptions": [],
  "confirmed": true,
  "country": "AR",
  "creationDate": "2023-02-27T15:48:08.534446Z",
  "creditParty": {
    "data": {
      "ACCOUNT_ID": "1000417"
    },
    "paymentMethodReference": "4447313534362D313030302E32233635",
    "type": "emoneyin-ars",
    "typeClass": "emoneyin",
    "typeCountry": "AR"
  },
  "currency": "ARS",
  "debitParty": {
    "data": {
      "document_number": "27381996900",
      "document_type": "ruc",
      "first_name": "Emmanuel",
      "last_name": "Lopez"
    },
    "type": "virtualaccount1in-ars",
    "typeClass": "virtualAccount",
    "typeCountry": "AR"
  },
  "descriptionText": "virtual account deposit",
  "fees": {
    "creditPartyEarnedCommission": "0.00000000",
    "creditPartyNetCommission": "0.00000000",
    "creditPartyPaidCommission": "0.00000000",
    "debitPartyEarnedCommission": "0.00000000",
    "debitPartyNetCommission": "0.00000000",
    "debitPartyPaidCommission": "0.00000000"
  },
  "fx": {},
  "geoCode": "",
  "metadata": [
    {
      "creationDate": "2023-02-27T15:48:08Z",
      "key": "virtualAccountNumber",
      "value": "0000108200016842376606"
    },
    {
      "creationDate": "2023-02-27T15:48:08Z",
      "key": "SV_TRANSACTION_ID",
      "value": "106588"
    },
    {
      "creationDate": "2023-02-27T15:48:08Z",
      "key": "phoneNumber",
      "value": "  "
    },
    {
      "creationDate": "2023-02-27T15:48:08Z",
      "key": "virtualAccountKey",
      "value": "27381996900"
    },
    {
      "creationDate": "2023-02-27T15:48:08Z",
      "key": "documentId",
      "value": "27357132385"
    },
    {
      "creationDate": "2023-02-27T15:48:08Z",
      "key": "personType",
      "value": "COMPANY"
    },
    {
      "creationDate": "2023-02-27T15:48:08Z",
      "key": "firstName",
      "value": "Gonzalo Ezequiel Torres"
    },
    {
      "creationDate": "2023-02-27T15:48:08Z",
      "key": "documentType",
      "value": "ruc"
    },
    {
      "creationDate": "2023-02-27T15:48:08Z",
      "key": "conciliationId",
      "value": "9e2c9c9a-d0cT-4729-81c4-3d18c9874Gfc"
    },
    {
      "creationDate": "2023-02-27T15:48:08Z",
      "key": "address",
      "value": "   "
    },
    {
      "creationDate": "2023-02-27T15:48:08Z",
      "key": "email",
      "value": "[email protected]"
    }
  ],
  "modificationDate": "2023-02-27T15:48:08.676746Z",
  "recipientKyc": {},
  "requestDate": "2023-02-27T15:48:08Z",
  "requestingOrganisationTransactionReference": "",
  "senderKyc": {},
  "subType": "virtual-account",
  "transactionReference": "1004102",
  "transactionStatus": "finished",
  "transactionSubStatus": "finished",
  "type": "deposit"
}’

Updated 3 days ago