WaaSabi API (1.0)

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

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

• Users
• Authentication
• Wallet Management
• User/Wallet Management
• Wallet Operations
• Cards
• Transfers

Special terms can be consulted in the Glossary.

The WaaSabi API is only allowed to be reached by authorized consumers using network address filtering. As a secure REST API, it is processed through HTTPs requests.

Note: Network address filtering for the sandbox is disabled, so it can be reached from any origin.

Authorization

WaaSabi API is protected by an OAuth 2.0 authorization scheme, through which an access_token is acquired. These tokens are then included in the HTTP headers of requests to WaaSabi using the Authorization: Bearer (IETF RFC) scheme. OAuth access tokens expire, so it is necessary to renew them periodically.

The API consumer is to obtain OAuth tokens by calling a specific endpoint of the identity platform. This is done by using a Client ID and Client Secret that is provided at the time of integration. As an example, for Sandbox you must use the following request:

curl --request POST 'https://auth-sbx.daxiaplatform.com/oauth2/token' \
     --header 'Authorization: Basic NTA3MnUyMDZmMmdjOGh2ZWVudmczaGw1OHY6dDNycXRiZjBoZ2E5YWd0bzI4cWM4aHNmaDQyY2dnMDIxNnV1NDRyaG8wdDZwY2g0bzRh' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'grant_type=client_credentials' \
     --data-urlencode 'client_id=5072u206f2gc8hveenvg3hl58v' \
     --data-urlencode 'scope=waasabi/api'

Response Example:

{
    "access_token": "eyJraWQiOiJaSEF5VFwvNlwvMWlxd3hYYTRKWWRReUNkeHJ5cStzZGtHSHJqT1VCNCtvcW89IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI1MDcydTIwNmYyZ2M4aHZlZW52ZzNobDU4diIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoid2Fhc2FiaS1zYW5kYm94XC9lbWFpbCIsImF1dGhfdGltZSI6MTY3OTA3MTA2NCwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLmV1LXdlc3QtMy5hbWF6b25hd3MuY29tXC9ldS13ZXN0LTNfbGpZcWcxdU84IiwiZXhwIjoxNjc5MDc0NjY0LCJpYXQiOjE2NzkwNzEwNjQsInZlcnNpb24iOjIsImp0aSI6IjE3ZmY0ZGEyLWI2MjEtNDc3OC05ZjkzLWZiNWE5Nzg5ODE1NCIsImNsaWVudF9pZCI6IjUwNzJ1MjA2ZjJnYzhodmVlbnZnM2hsNTh2In0.Kh95fNC7yiCZBDyIvnkrnZK88mB2BTalP94F4J80nUPZFHwhWBGEtKaBxPaTkxVBovA6jk0QPFp84mPCsNgRF9q4xDygo6GDFIxXIkrlu0Epk-PVpAhE35hV31nYNyEf-FMen7UA5kXYdijeZBxe5S2gF2xjF9ezAb7EER2aGZaMKMsDxF51tjXOKWMqAoCnqTDUNfjLQVn6A8lWvOa5255lfhLPt9q_hQtJum_vxhvr3ydP-p7RRD4oewGvaSN5HwS7A-9SUgqTYXBuugDJQkHzI6v0bV9_5kHUfu-PcBiDNVdzhFaDV9Q8TIGwIFbrF-G8dB8PdkdTbP2moBjyUg",
    "expires_in": 3600,
    "token_type": "Bearer"
}

You need to use the access_token returned in the header of every request you send to WaaSabi API. This token expires in one hour, so it is necessary to renew it periodically.

WaaSabi uses conventional HTTP status codes to indicate the success or failure of an API request. However, in the event of a business rule failure, WaaSabi will respond with the HTTP OK code (200) and detail the failure in the response body. Therefore, responses returned by WaaSabi 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 WaaSabi 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"
}

WaaSabi 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.

WaaSabi allows any client to implement a data delegation scheme for their users, partially or totally. There are minimum implementation conditions that enable access to the different services of the platform, which will be explained below.

Create User

Use the Create User endpoint to register them on the platform. According to the consumer configuration, the corresponding wallets will be created and linked to the user.

Once created, the user will be able to perform operations such as Cash-In Transactions, Transfers to External Bank Accounts, Obtaining Wallet Transactions, etc.

The only mandatory value is the username, which must be unique. The response will return an ID which will be used for all subsequent operations related to the user (being Get User by username one of a few exceptions).

curl --request POST 'https://api-sandbox.daxiaplatform.com/sandbox/api/v1/user' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "username": "johndoe",
         "name": "John",
         "surname": "Doe",
         "email": "john.doe@acme.com",
         "phone_number": "5493513453335",
         "birth_date": "1980-03-23"
    }'

Response:

{
  "error": false,
  "response": {
    "id": 81,
    "company_id": 1234,
    "default_wallet_id": 66,
    "username": "johndoe",
    "name": "John",
    "surname": "Doe",
    "email": "john.doe@acme.com",
    "phone_number": "5493513453335",
    "birth_date": "1980-03-23",
    "has_pin": false,
    "deleted": false,
    "blocked": false,
    "full_name": "John Doe"
  }
}

Update user data

You can update the user’s personal information (first name, last name, etc.) through the Update User endpoint.

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.

Based on business rules and security compliance rules, it will be necessary to validate the user's identity using credentials of varying strength, such as passwords or liveness confirmation. The Authentication Module provides endpoints for the management of user passwords and liveness detection, among other specific functionalities.

WaaSabi allows the implementer to apply execution rules to verify if the users meets the conditions for a certain operation. See Validate the user's requirements to execute an operation for the functionality to verify if a user is blocked, if he has permission to execute an operation and anti-fraud rules, among other things.

Also see Verify if the Password is recent to validate the user's credential expiration.

Add a password to a user

If it was required for example to add the password 123 to the user with ID 3, the endpoint Create Password should be used:

curl --request POST 'https://api-sandbox.daxiaplatform.com/sandbox/api/v1/user/3/auth/password' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "password": "123"
    }'

Response:

{
    "error": false
}

The Wallets Management module in WaaSabi 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:

Create Wallet

To create a wallet for a user, you need to use the Create Wallet endpoint. This will create a new wallet and associate it with the user. The endpoint requires a request body with the necessary details, such as the user ID and other optional information.

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

Response:

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

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/v1/wallet/123' \
     --header 'Authorization: Bearer <access_token>'

Response:

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

Update Wallet Information

If you need to update the information of a specific wallet, you can use the Update Wallet endpoint. It requires the walletId as a path parameter and a request body with the updated wallet information.

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

Response:

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

Delete Wallet

To delete a specific wallet, you can use the Delete Wallet endpoint. It requires the walletId as a path parameter. Deleting a wallet will permanently remove it from the system.

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

Response:

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

Search Wallets

If you want to search for wallets based on specific codes and values, you can use the Search Wallets endpoint. It requires the codes and values as query parameters to filter the wallets. The response will include a list of matching wallets.

curl --request GET 'https://api-sandbox.daxiaplatform.com/sandbox/api/v1/wallet?codes=code1,code2&values=value1,value2' \
     --header 'Authorization: Bearer <access_token>'

Response:

{
  "error": false,
  "response": [
    {
      "id": 123,
      "userId": 81,
      "currency": "USD",
      "balance": 100.0
    },
    {
      "id": 456,
      "userId": 82,
      "currency": "EUR",
      "balance": 50.0
    }
  ]
}

The codes and values parameters allow you to search for wallets that match specific criteria. Multiple codes and values can be provided, separated by commas.

The User-Wallet Management module in WaaSabi allows clients to manage the association between users and wallets. This module provides endpoints to assign wallets to users, retrieve wallets associated with users, and manage the relationship between users and wallets. Here's how the module works:

Add Wallet to User

To assign an existing wallet to a user, you can use the Add Wallet to User endpoint. This endpoint requires the userId as a path parameter and a request body with the wallet details.

curl --request PUT 'https://api-sandbox.daxiaplatform.com/sandbox/api/v1/user/{userId}/wallet' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "walletId": 123
    }'

Response:

{
  "error": false,
  "response": {
    "id": 123,
    "userId": {userId},
    "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. This endpoint requires the userId as a path parameter and a request body with the wallet details.

curl --request POST 'https://api-sandbox.daxiaplatform.com/sandbox/api/v1/user/{userId}/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
  }
}

Get Wallet Information by User

To retrieve the details of a specific wallet associated with a user, you can use the Get Wallet Information by User endpoint. This endpoint requires the userId and walletId as path parameters.

curl --request GET 'https://api-sandbox.daxiaplatform.com/sandbox/api/v1/user/{userId}/wallet/{walletId}' \
     --header 'Authorization: Bearer <access_token>'

Response:

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

Update Wallet by User

If you need to update the information of a specific wallet associated with a user, you can use the Update Wallet by User endpoint. This endpoint requires the userId and walletId as path parameters, and a request body with the updated wallet information.

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

Response:

{
  "error": false,
  "response": {
    "id": {walletId},
    "userId": {userId},
    "currency": "EUR",
    "balance": 0.0
  }
}

Disassociates Wallet from User

To disassociate a specific wallet from a user, you can use the Disassociates Wallet from User endpoint. This endpoint requires the userId and walletId as path parameters.

curl --request DELETE 'https://api-sandbox.daxiaplatform.com/sandbox/api/v1/user/{userId}/wallet/{walletId}' \
     --header 'Authorization: Bearer <access_token>'

Response:

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

Get Users by Wallet

To retrieve a list of all users associated with a specific wallet, you can use the Get Users by Wallet endpoint. This endpoint requires the walletId as a path parameter.

curl --request GET 'https://api-sandbox.daxiaplatform.com/sandbox/api/v1/wallet/{walletId}/users' \
     --header 'Authorization: Bearer <access_token>'

Response:

{
  "error": false,
  "response": [
    {
      "id": {userId},
      "username": "johndoe",
      "name": "John",
      "surname": "Doe",
      "email": "john.doe@acme.com",
      "phone_number": "5493513453335",
      "birth_date": "1980-03-23"
    },
    {
      "id": {userId},
      "username": "janedoe",
      "name": "Jane",
      "surname": "Doe",
      "email": "jane.doe@acme.com",
      "phone_number": "5493513453336",
      "birth_date": "1982-06-12"
    }
  ]
}

Get Wallets by User

To retrieve a list of all wallets associated with a specific user, you can use the Get Wallets by User endpoint. This endpoint requires the userId as a path parameter.

curl --request GET 'https://api-sandbox.daxiaplatform.com/sandbox/api/v1/user/{userId}/wallets' \
     --header 'Authorization: Bearer <access_token>'

Response:

{
  "error": false,
  "response": [
    {
      "id": 123,
      "userId": {userId},
      "currency": "USD",
      "balance": 0.0
    },
    {
      "id": 456,
      "userId": {userId},
      "currency": "EUR",
      "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.

Business Models

The operations that the implementer will allow their users to have depends on the business model they pursue. We present here two models which are commonly used.

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.

Aggregator Model

Aggregators offer a collection of services to an existing user base of customers or merchants. Transactions take place in a centralized way, between the aggregator and its users. Of course, P2P and aggregator models can be combined.

If the implementer has an "Aggregator" business model, they can implement a set of endpoints that allows making cash-ins through a Transaction of cash inflow, sending money from one merchant to the company with Send money to the company or send money between WaaSabi wallets through Instant P2P money transfer (this endpoint can of course also be used in the "Peer to Peer" Model).

Verify balance example

To obtain the balance of the wallet of a user with ID 3 and the wallet with ID 4, the endpoint Retrieve User Wallet Information should be used:

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

Response:

{
    "error": false,
    "response": {
        "id": 4,
        "status": "ACTIVE",
        "company_id": 1234,
        "currency": "USD",
        "balance": 10.00,
        "available_balance": 10.00,
        "additional_info": {
            "customer_id": "3"
        }
    }
}

It allows users to manage their means of payment with which they operate and to securely store their bank card information. WaaSabi 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/v1/user/3/card' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "card_holder_name": "ERIK PETERSON",
         "alias": "Alias",
         "issuer_code": "800",
         "issuer_name": "AMEX",
         "token": "49422442Aj8A4791",
         "first_six_digits": "494229",
         "last_four_digits": "4478",
         "expiration_month": 3,
         "expiration_year": "24",
         "payment_method_code": "AMEX",
         "payment_method_name": "AMEX",
         "payment_method_type": "CREDITO",
         "brand": "AMEX",
         "hmac_token": "DM5CI1S0ZNwQiCdGXME2YAcEYibaYb+X6j4w46uSNHE="
    }'

Response:

{
    "error": false,
    "response": {
        "id": "1",
        "customer_id": "3",
        "card_holder_name": "ERIK PETERSON",
        "alias": "Alias",
        "issuer_code": "800",
        "issuer_name": "AMEX",
        "token": "49422442Aj8A4791",
        "first_six_digits": "494229",
        "last_four_digits": "4478",
        "expiration_month": 3,
        "expiration_year": 24,
        "payment_method_code": "VISA",
        "payment_method_name": "VISA",
        "payment_method_type": "CREDIT",
        "brand": "VISA",
        "hmac_token": "DM5CI1S0ZNwQiCdGXME2YAcEYibaYb+X6j4w46uSNHE="
    }
}

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 WaaSabi can use this information to make payments without having to store the card's sensitive data.

As a WaaSabi 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 WaaSabi. With this OTA, the application frontend will be able to tokenize the card data, send it to the backend, which then saves it on WaaSabi.

Generate OTA:

First, the OTA is requested from the backend to WaaSabi. 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/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 WaaSabi.

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/v1/user/1/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/v1/user/3/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"
            }
        ]
    }
}

Idempotency Checks

WaaSabi can optionally perform idempotency checks when receiving the Idempotency-Key header (IETF Draft). These checks have the purpose of avoiding duplicate or conflicting data from entering the database when communication errors occur and requests are sent several times. The idempotency key is an opaque value that can be chosen by the API consumer as long as it doesn't change between two or more request instances that belong to the same operation (several instances may be invoked due to for example a network timeout, page reloads or interrupted connections).

To perform idempotency checks, WaaSabi checks if the provided key has been previously used within the last 5 minutes. If the key has been used within this time frame, WaaSabi will reply with HTTP Status 409 (Conflict). Otherwise the request will be allowed and thus processed. Idempotency checks can be used for any WaaSabi call.

Example:

curl --request POST 'https://api-sandbox.daxiaplatform.com/sandbox/api/v1/customer' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Idempotency-Key: 324578093452' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "username": "johndoe",
         "name": "John",
         "surname": "Doe",
         "email": "john.doe@acme.com",
         "cellPhone": "5493513453335",
         "birth_date": "1980-03-23",
         "currency": "ARS"
    }'

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

Endpoint Implementation

You must implement a primary entry point for receiving notifications from WaaSabi. 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 WaaSabi 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 WaaSabi 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

WaaSabi 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 WaaSabi. 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 WaaSabi 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 WaaSabi, 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 WaaSabi 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