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

POST /protocol/openid-connect/token


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}}'

‍

200 (OK)

{
    "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

GET /paymentmethodtypes


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}}' 

‍

200 (OK)

[
    {
        "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

POST /virtualAccount

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"
    }
}'

‍

202 (Accepted)

{
    "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

PUT /callback.test

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

PUT /callback.test

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": "mail@mail.com"
    }
  ],
  "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"
}’

‍

‍