This section offers hands-on information to implementers, functional analysts, product analysts and anyone involved with the integration of the Daxia Users platform.

The implementer team has a collection of Daxia User API objects at their disposal with the following modules:

• User
• Authentication
• Cards
• Transfers

Special terms can be consulted in the Glossary.

The Daxia User API is not restricted by network address filtering as the Corporate API. As a secure REST API, it is processed through HTTPs requests using the following scheme.

Authorization

Daxia User API is protected by an authorization scheme. Each user needs to acquire an access_token through the Corporate API by calling the Get User Token endpoint. That token must then included in the HTTP headers of requests to Daxia using the Authorization: Bearer (IETF RFC) scheme. The User Token is designed to be permanent and does not require periodic renewal, except in cases where it may have been compromised.

The User API consumer is to ontain the access token from the Company that created the user. Tipically the Company should provide a functionality that calls the Get User Token endpoint on the Corporate API. You can test this endpoint in the sandbox environment:

curl --request GET 'https://api-sandbox.daxiaplatform.com/sandbox/api/v1/user/123/token' \
     --header 'Authorization: Bearer <access_token>'

Response Example:

{
    "error":false, "response":"eyJraWQiOiJaSEF5VFwvNlwvMWlxd3hYYTRKWWRReUNkeHJ5cStzZGtHSHJqT1VCNCtvcW89IiwiYWxnIjoiUlMyNTYifQmYyZ2M4aHZlZW52ZzNobDU4diIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoid2Fhc2FiaS1zYW5kYm94XC9lbWFpbCIsImF1dGhfdGltZSI6MTY3OTA3MTA2NCwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8",
}

You then need to use the response string returned as access_token in the header of every request you send to Daxia User API.

Daxia uses conventional HTTP status codes to indicate the success or failure of an API request. However, in the event of a business rule failure, Daxia will respond with the HTTP OK code (200) and detail the failure in the response body. Therefore, responses returned by Daxia can be dividen in 3 scenarios:

• Successful operations
• Operations that did not pass business rules
• Internal or external service errors

Successful Operations

An HTTP OK code (200) is returned as usual, with a JSON response body. The response consists of an "error" field with the false value and an optional "response" field with the resulting object, if any.

Example:

{
  "error": false,
  "response": { … }
}

Operations that did not pass business rules

In this case, an HTTP OK code (200) is also returned, but the response consists of an "error" field with value true and an "error_information" field with a detailing object.

Available "code" values are described in Daxia Error Codes.

Example:

{
  "error": false,
  "error_information": {
    "code": "EXC_01",
    "message": "Error executing operation",
    "error_detail": "TBD"
  }
}

Internal or external service errors

The response body will come with a JSON object detailing the situation and one of the following HTTP error codes will be returned:

Example:

{
    "timestamp": "2022-11-30T14:27:13.762+00:00",
    "status": 502,
    "error": "Fraud provider response is empty (wrong API-KEY?)",
    "message": "",
    "path": "/v1/user/123"
}

Daxia provides a Sandbox environment for developers to mimic the characteristics of the platform and create simulated responses from all APIs. The Sandbox is publicly reachable so that developers can freely perform their tests regardless of location.

All curl request examples in this document point to the Sandbox environment.

Important: Databases in this environment are reset every day.

Register Callback Endpoint

The Daxia user has the option to create and/or update the webhook link so that this URL is notified when certain operations are performed by the Daxia API. It's useful to ensure that Daxia always has the correct address to notify the user about relevant events or updates.

Block and Unblock user

Blocking a user will prevent them from performing operations. To block a user, one of the available reasons must be provided. When the Block User action is invoked, the reason specified is added to the list of reasons that block the user, and the platform will not allow them to perform operations until all those reasons are removed by calling Unblock User.

The invocation of these actions will not affect the user's record, movements and other transactions previously performed.

The Wallets Management module in Daxia allows clients to manage wallets associated with users. Users can perform various operations related to their wallets, such as cash-in transactions, transfers to external bank accounts, and obtaining wallet transactions. Here's how the module works:

Get Wallet Information

To retrieve the details of a specific wallet, you can use the Get Wallet Information endpoint. It requires the walletId as a path parameter and returns the wallet details in the response.

curl --request GET 'https://api-sandbox.daxiaplatform.com/sandbox/api_user/api/user/v1/wallet/123' \
     --header 'Authorization: Bearer <access_token>'

Response:

{
  "error": false,
  "response": {
    "id": 123,
    "userId": 81,
    "currency": "USD",
    "balance": 0.0
  }
}

Create Wallet for User

If you want to create a new wallet and assign it to a user, you can use the Create Wallet for User endpoint.

curl --request POST 'https://api-sandbox.daxiaplatform.com/sandbox/api_user/api/user/v1/wallet' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "currency": "USD"
    }'

Response:

{
  "error": false,
  "response": {
    "id": 123,
    "userId": {userId},
    "currency": "USD",
    "balance": 0.0
  }
}

It contains a set of endpoints that allows users to operate the balances of their respective digital wallets. Among other things, they can deposit, send and request money, check their balance and check the transaction history of either their wallet or bank cards.

Peer-to-Peer Payments

The "P2P" business model is about allowing users to transact with each other. The implementer can a set up endpoints that run sequentially to allow users to send and request money to and from other users.

To send money, first execute the endpoint to Reserve funds for sending a money transfer, followed by Credit funds from a money Transfer to complete the transaction. To request money, Money Transfer Request is to be executed, followed by Credit funds to the recipient of a Money Transfer Request.

It allows users to manage their means of payment with which they operate and to securely store their bank card information. Daxia is a PCI DSS compliant platform, a certification required by credit card issuers to ensure the security of transactions in the payment industry.

It is also possible to obtain the data of a particular card, as well as all the cards that a user has stored.

In the event that the user no longer wishes to store a card's data, the delete card endpoint can be used.

Add card to a user example

To for example add a card to a user with ID 3 for subsequent operations, the endpoint Add a Card should be used:

curl --request POST 'https://api-sandbox.daxiaplatform.com/sandbox/api_user/api/user/v1/card' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "alias": "Alias",
         "token": "DM5CI1S0ZNwQiCdGXME2YAcEYibaYb",
         "last_four_digits": "4478"
    }'

Response:

{
    "error": false,
    "response": {
        "id": 30,
        "alias": "AMEX Corporativa",
        "token": "49422442Aj8A4791",
        "last_four_digits": "7124",
        "customer_id": 153,
        "creation_date": "2022-07-21 12:56:33",
        "additional_info": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "wallet_id": 153,
        "reference_id": "string",
        "currency": "ARS",
        "status": "ACTIVE"
      }
}

Tokenization is a technique used to replace sensitive information throughout a system with surrogate strings called tokens. Sensitive information is stored in a vault and a corresponding token is returned through a service called a tokenizer. Tokens can then be used as an in-place replacement of the original sensitive information, and as a key for retrieving the information later on. Access to sensitive information is only granted during critical operations that require such information, and can only be retrieved from the vault by authorized consumers.

Using tokenization, sensitive information of bank cards is kept in a separated and secured system, so Daxia can use this information to make payments without having to store the card's sensitive data.

As a Daxia implementer, your first requirement is not to send any card's sensitive information to the backend, so the tokenization must be performed from the frontend. Before displaying the frontend, your application backend must obtain a "One Time Authorization" token (OTA) from Daxia. With this OTA, the application frontend will be able to tokenize the card data, send it to the backend, which then saves it on Daxia.

Generate OTA:

First, the OTA is requested from the backend to Daxia Api User. The resulting string is then sent to the frontend so it can use it one time to generate the token in direct communication with the tokenizer. The expiration time forces the tokenization request to be submit within the number of seconds provided, after the OTA's creation.

curl --request POST 'https://api-sandbox.daxiaplatform.com/sandbox/api_user/api/user/v1/one-time-authorization' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "expire_time_seconds": 3600
    }'

Response:

{
    "error": false,
    "response": "00tFhFsgJofEwaOXFm0yUQ=="
}

Save Card information and generate Token:

With the OTA obtained in the previous step your frontend is able to call the tokenizer to save the card information and receive the corresponding token to send to Daxia.

This request is sent from the backend directly to the tokenizer:

curl --request POST 'https://api-sandbox.daxiaplatform.com/sandbox/tokenizer/api/v1/tokenize' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "data": {
             "cardNumber": "4545123456123456",
             "cardHolderName": "Philippe Bouchpies",
             "cardExpirationMonth": "12",
             "cardExpirationYear": "26"
         },
         "expireTimeSeconds": "45687898789",
         "oneTimeAuthorization": "00tFhFsgJofEwaOXFm0yUQ=="
    }'

Response:

{
    "token": "tk185#xpCuqlyzkR896akKIodJ/jqMrlqjSpAEt6LiVtA7iGyZoHM9xtfK/PqfargUmfvf",
    "signature": "fvfmUgrafqP/Kftx9MHoZyGi7AtViL6tEApSjqlrMqj/JdoIKka698RkzylquCpx#581kt"
}

This token is used for some operations such as Add Card. This token will be saved to carry out card operations such as making payments. The signature is used to verify through a provided public key that the token was generated by the tokenizer itself, to avoid man-in-the-middle attacks.

Finally, add the card using the token:

curl --request POST 'https://api-sandbox.daxiaplatform.com/sandbox/api_user/api/v1/user/card' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "alias": "AMEX Corporate",
         "token": "tk185#xpCuqlyzkR896akKIodJ/jqMrlqjSpAEt6LiVtA7iGyZoHM9xtfK/PqfargUmfvf",
         "last_four_digits": 7124
    }'

Note that most of the card information was not included, because it was stored in the tokenizer's vault.

Contains the endpoints that allow users to make transfers to bank and/or virtual accounts. The transfer destination options depend on the systemic conditions of the different countries where the implementation takes place.

curl --request POST 'https://api-sandbox.daxiaplatform.com/sandbox/api_user/api/user/v1/wallet/4/cash_out' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "amount": 2,
         "metadata": {},
         "receiver": {
             "name": "Jane",
             "last_name": "Doe",
             "birth_date": "1991-08-15",
             "government_identification": "7329034129",
             "government_identification_type": "DNI",
             "bank_name": "SANTANDER RIO",
             "bank_account": "00496561886143650075",
             "account_type": "Corriente",
             "bank_province": "Buenos Aires",
             "bank_city": "Mar del Plata",
             "address": "2000 Arenales",
             "city": "Lanús",
             "postal_code": "1822",
             "email": "janedoe@gmailcom",
             "phone": "+541176334600",
             "metadata": {
                 "key1": "value1",
                 "key2": "value2"
             }
         }
    }'

Response:

{
    "error": false,
    "response": {
        "transactions": [
            {
                "id": 2,
                "wallet_id": 4,
                "company_id": 1234,
                "transaction_status": "CONFIRMED",
                "amount": -2,
                "balance": 8.00,
                "available_balance": 8.00,
                "removed": false,
                "transaction_date": 1669941943971,
                "additional_info": {
                    "provider": "SEPA",
                    "name": "string",
                    "customer_id": "3",
                    "transaction_type": "CASH_OUT",
                    "operation": "CASHOUT",
                    "destination_account": "string",
                    "lastname": "string"
                },
                "currency": "USD"
            }
        ]
    }
}

Daxia will notify your backend about different events using a callback mechanism. This section explains how to implement these callbacks for efficient interaction with Daxia.

Endpoint Implementation

You must implement a primary entry point for receiving notifications from Daxia. Following an example in JAVA

@RestController
@CrossOrigin
@RequestMapping(value = "/notifications")
public class CallbackController {
    // Implementation here
}

Sample Callback Data

Here's a sample data model sent by Daxia when an invoice is paid.

{
    "customer_id": 1234,
    "company_id": 5678,
    "notification_type": "INVOICE_PAID",
    "metadata": {
        "key1": "value1",
        "key2": "value2"
    }
}

Check the Notification Types table to get the possible values of the notification_type field.

Handling User Blocking and Unblocking

Caching Users

To avoid making frequent API calls to Daxia for each user interaction, it is highly recommended to cache user details on your backend. This makes operations more efficient.

Responding to Block and Unblock Notifications

Daxia will send notifications of type BLOCK or UNBLOCK to indicate the change in a user's status.

What To Do When A User Is Blocked

When you receive a BLOCK notification, you should immediately remove the user from your cache. The next time this user tries to interact with your service, you will need to fetch the updated user details from Daxia. Because the user is blocked, prevent them from performing any actions.

What To Do When A User Is Unblocked

When you receive a UNBLOCK notification, you can either:

• Remove the user from the cache so that the user details get refreshed the next time they interact, or
• Update the user status in your cache to unblocked.

API Consumer : Any part of the solution that sends requests to Daxia and is authorized to do so.

Bank Card : A Debit or Credit Card issued by a bank or a credit union. Other types of cards may be accepted by Daxia, such as Chard Cards and Prepaid Cards, but it depends that they are operable by the banking provider.

Bill : See Transfer Ticket.

BIN : Bank Identification Number. The first six digits of a Bank Card number, which uniquely identify the institution that issued the card. The first digit is the major industry identifier, and the remaining digits communicate the financial institution that issued the card.

Card : A Bank Card.

Cutomer : Deprecated term for User.

CVV, CSC or CVC : Card Verification Value, Card Security Code or Card Verification Code. It's a three (Visa/MC) of four (AMEX) digit number printed in the back of the card for additional security for online transactions where the card holder is not physicaly present with the merchant.

ID or Identifier : An ID for an entity is a 64-bit integer number that uniquely represents that entity among entities of the same type. When an entity is created, a new ID for its record is created and returned from the call, and that number can be used to unambiguously refer to that entity in the future. An exception is the "Government ID", which refers to a physical document issued to citizens or residents of a country to identify them.

Idempotence : Idempotence is the property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application. It does not matter if the operation is called only once, or 10s of times over. The result SHOULD be the same.

Implementer : The business who is integrating Daxia with their systems to provide financial services to their users.

Merchant : A business that uses the implemented system to expand the offering to their own customers.

P2P : Peer-to-peer. Business model whose essence is the interaction between users.

PCI DSS : It's the Payment Card Industry Data Security Standard. For more information, visit the official website.

Security Code : See CVV

Ticket Token : Also known as Ticket ID. Used as a reference for a Transfer Ticket.

Transfer Ticket : Transfer tickets are created as a point of contact with which a User specifies a future transaction to either send funds (Outgoing transfer, pay), or receive funds (Incoming transfer, charge or request money). The ticket stores the information required to perform the transaction and is referenced using a Ticket Token. When the ticket is executed, the transfer is executed according to the information provided in the ticket and parameters sent then.

User : A customer, if used with no other qualifier. Users who register their own banking accounts and perform transfers, payments, deposits and so on.

Actions on the User

Authorization of Operations

Wallet Operations

Perform External Transfer between Bank Accounts