Your APIs for us - External Balance

External Balance 

Features

Purpose and scope

Terminology

To use external balance you must have Banking License or Payment Institution License. Additionally if you don't directly own BIN range, total sum of transactions of your users will be limited by deposit called "Master Balance".

Security

To set secured server-server connection between our services Verestro requires a similar connection as in the case of client to Verestro communication based on the x509 certificate, more about this model here.
In the first step, Verestro will send to the client a CSR for the dev and production environments, more details here.
The next step is for the client to sign the CSR and send the certificate back to Verestro along with the base URL for the methods listed below. Verestro will authorize itself with each request with a certificate, which should be checked on the client side.

Idempotency Key

With some requests additional header X-Idempotency-Key could be send. This header contain unique random id allowing to identify single request.
If client send this header, operation should be triggered only once and for any further request with this key, response should be identical - in most cases, returned from cache.

example headers:

X-Idempotency-Key: 20e87975-dbfb-4c95-b239-169516c0b707

External Balance API

Below you will find a list of endpoints that you should implement on your server side. Please pay special attention to the appropriate security of our connection, the syntax of requests that you can expect from the Verestro side, idempotency and the exact way in which you should respond to each request.

Process of linking balances

@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
participant "Client server" as cs
participant Antaca as a
participant Lifecycle as lc
cs->lc: 1. create user by POST /wallet (firstName, lastName, phone, email)
lc-->cs: 2. userId
alt With own KYC process
cs->lc: 3. update KYC status by PUT /user (KYC)
else With Verestro KYC process
cs->a: 4. send KYC data by /register (user data with documents and selfie)
a->a: 5. process KYC
a->lc: 6. update KYC status
end
alt With automatic balance creation
lc-->a: 7. event about the new user with KYC
a->a: 8. create a balance in the default currency
a->cs: 10. link balance (userId, balanceId, currency)
cs-->a: 11. 204 (OK)
else Every time with create a balance
cs->a: 9. create balance by POST /balance (userId, currency)
a->cs: 10. link balance (userId, balanceId, currency)
cs-->a: 11. 204 (OK)
a-->cs: 12. 201 balance created
end

@enduml

• send a GET requests to retrieve information about specific balance. Using user ID and/or balance ID, Antaca can obtain information about balance currency and money amount.
• send a GET requests to retrieve information about all user’s balances. Using only user ID Antaca can retrieve list of users balances.
• delete link between balances

Remember to avoid billing problems
Deleting a balance is only possible when its status is 0. This also applies to situations in which a user with at least one balance is deleted.

Transaction processing 

Remember to avoid communication errors
Verestro servers attach an X-Idempotency-Key to each request in the header. This header contains a unique ID for each request to ensure idempotence. Each request with a unique identifier in this header should be processed only once on the client side and the response to it should be identical - in most cases, returned from cache

example:

curl POST "https://server-domain.com/transactions/debit"
--header "X-Idempotency-Key: 21aa0c2a-5554-4071-bd48-b9c64a0b6270"

Transaction object

{
    "id": "b4f534ef-77c2-4f16-ab4d-496806a76fb6",
    "balanceId": "b334b384-328c-11ed-a261-0242ac120002",
    "resourceId": "9d673932-3291-11ed-a261-0242ac120002",
    "resource": "card",
    "transactionId": "ab3d89e4-3291-11ed-a261-0242ac120002",
    "referenceTransactionId": "b759931c-3291-11ed-a261-0242ac120002",
    "type": "POS",
    "amount": 10000,
    "currency": "PLN",
    "originalAmount": 10000,
    "originalCurrency": "PLN",
    "status": "AUTHORIZED",
    "description": "transaction description",
    "date": "2020-08-17T18:43:42+00:00",
    "transactionData": {
        "mcc": "5942",
        "merchantIdentifier": "003060300000005",
        "merchantName": "Book store",
        "captureMode": "NFC",
        "lastFourDigits": "4560",
        "acquirerCountry": "PL",
        "mdesDigitizedWalletId": "Google Pay",
        "cashbackPosCurrencyCode": "PLN",
        "cashbackPosAmount": 10000,
        "paymentTokenLastFourDigits": "7890",
        "adjustmentReasonDescription": "REFUND",
        "retrievalReferenceNumber": "749248185012"
    }
}

Integration with External Balance

API External balance 

For the process to function correctly, the Client must implement all endpoints detailed in this chapter.

Below you will find a list of endpoints that you should implement on your server side. Please pay special attention to the appropriate security of our connection, the syntax of requests that you can expect from the Verestro side, idempotency and the exact way in which you should respond to each request. If you decide to implement external balance to be able to keep the balance on your side and authorize transactions, remember that the implementation of all the methods below is required to ensure the API works.

Link balance

This method is used to link customer balance between client and server. Requested balanceId will be used for communication between client and Verestro side.

If you create balance entity at your end you should create it after receiving this call. Do not create balance entity on your side as result of POST /secure/balances nor POST /secure/customers/{id}/balances, because link balance will be called before response to these methods.

POST https://server-domain.com/users/:id/balances

path parameters:

id - user identifier

Headers:

Content-Type: application/json
Accept: application/json

request body:

{
    "balanceId":"2e520dc2-329d-11ed-a261-0242ac120002",
    "currency": "PLN"
}

parameters:

balanceId - unique identifier of balance in format: uuid v4. This ID will be used in communication between client and server.
currency - required, should be 3 letters code in ISO 4217 https://www.iban.com/currency-codes

response:

204 NoContent

error codes:
404 - should be returned if no user has been matched by requested path parameter.

Code 404
{
    "title": "USER_NOT_FOUND",
    "detail": "some specific details provided by server"
}

Get single user balance

Method used to obtain single user balance information.

GET https://server-domain.com/users/:id/balances/:balanceId

path parameters:

id - user identifier
balanceId - unique balance identifier

headers:

Accept: application/json

response:

200 OK
{
    "currency": "PLN",
    "amount": 250
}

response parameters:

currency  - three letter iso 4217 code
amount - actual balance amount in minor (penny), integer value. For example: 12.34 EUR will be sent as 1234

error codes:
404 - should be returned if no balance found by requested balanceId.

Code 404
{
    "title": "BALANCE_NOT_FOUND",
    "detail": "some specific details provided by server"
}

403  - if requested balance does not belong to user.

Code 403
{
    "title": "FORBIDDEN",
    "detail": "some specific details provided by server"
}

Get balance collection

This method should return collection of customer balances.

GET https://server-domain.com/users/:id/balances

path parameters:

id - user identifier

headers:

Accept: application/json

response:

200 OK
[
    {
        "id": "a072bd0e-328c-11ed-a261-0242ac120001",
        "currency": "PLN",
        "amount": 250
    },
    {
        "id": "b334a5e2-328c-11ed-a261-0242ac120002",
        "currency": "USD",
        "amount": 460
    }
]

If user has not created any balance yet, there should be returned empty collection.

200 OK
[]

response parameters:

id - unique identifier of user balance
currency  - three letter iso 4217 code
amount - actual balance amount in minor (penny), numeric value

Delete balance

This method is used to unattached balance from user. From legal point of view, balance should be deleted only if there is no money on it.

DELETE https://server-domain.com/users/:id/balances/:balanceId

path parameters:

id - user identifier
balanceId - unique balance identifier

response:

204 No Content

error responses:

404 - if requested balance has not been found.

Code 404
{
    "title": "BALANCE_NOT_FOUND",
    "detail": "some specific details provided by server"
}

403 - if requested balance does not belong to user.

Code 403
{
    "title": "FORBIDDEN",
    "detail": "some specific details provided by server"
}

Debit transaction

This kind of transaction is used to authorize transaction. In debit transactions Antaca asks 'if user has money?'.

POST https://server-domain.com/transactions/debit

headers:

Content-Type: application/json
X-Idempotency-Key: uuidV4

request body:

Description of the contents of the transaction object can be found above.

success response:

204 No Content

error responses:

422
{
    "title": "INSUFFICIENT_FUNDS",
    "detail": "some specific details provided by server"
}

422
{
    "title": "LIMITS_EXCEEDED",
    "detail": "some specific details provided by server"
}

422
{
    "title": "FRAUDS_DETECTED",
    "detail": "some specific details provided by server"
}

404
{
    "title": "BALANCE_NOT_FOUND",
    "detail": "some specific details provided by server"
}

Force debit transaction

This kind of transaction is used to inform server side that transaction has occurred.
For this request, actual transaction already happen so server can not reject this request. This behavior can occur for offline transactions fe: in plane, subway, for refunds and referring to previously authorized transactions.

POST https://server-domain.com/transactions/force-debit

headers:

Content-Type: application/json
X-Idempotency-Key: uuidV4

request body:

Description of the contents of the transaction object can be found above.

response:

204 No Content

error response:

As mention in description section, we do not accept transaction rejection.

Credit transaction

Method is used to credit user balance. In credit transactions Antaca asks 'can user get money?'.

POST https://server-domain.com/transactions/credit

headers:

Content-Type: application/json
X-Idempotency-Key: uuidV4

request body:

Description of the contents of the transaction object can be found above.

success response:

204 No Content

error responses:

404
{
    "title": "BALANCE_NOT_FOUND",
    "detail": "cannot find requested balance"
}

422
{
    "title": "FRAUDS_DETECTED",
    "detail": "some specific details provided by server"
}

Force credit

Method is used to credit user balance. This kind of transaction is used to inform server side that transaction has occurred. For this request, actual transaction already happen so server can not reject this request.

POST https://server-domain.com/transactions/force-credit

headers:

Content-Type: application/json
X-Idempotency-Key: uuidV4

request body:

Description of the contents of the transaction object can be found above.

success response:

204 No Content

error response:

As mention in description section, we do not accept transaction rejection.

Reversal

Method is used to revert any changes for previous transaction. Request body will be identical to transaction witch client try to revert. If server cannot find referenced transaction then no action is required.

POST https://server-domain.com/transactions/reversal

headers:

Content-Type: application/json
X-Idempotency-Key: uuidV4

request body:

Description of the contents of the transaction object can be found above.

success response:

204 No Content

error responses:

IMPORTANT: for this method, we do not accept any error. Only satisfying behavior is to revert referenced transaction and no action if cannot find transaction.

Update transaction status

From time to time, client will  inform about clearings triggered by acquirer side. If client mark transaction as cleared it means that transaction will not be corrected by any other transaction request and requested amount is final.

PUT https://server-domain.com/transactions/:id

path parameters:

id - transaction identifier

request body:

Description of the contents of the transaction object can be found above.

success response:

204 No Content

error responses:

404
{
    "title": "TRANSACTION_NOT_FOUND",
    "detail": "cannot find requested transaction"
}

Transaction Types Description

Debit transactions list: 

Credit transactions list: