PayCaddy API Documentation

Easily integrate card issuance into your apps and systems.

Intro

Welcome to the Paycaddy API documentation, a comprehensive and flexible platform designed to enable businesses and developers to easily integrate banking and financial services into their applications and systems.

Our API is built as a REST interface. The main benefit is that it accepts form-encoded request bodies and returns JSON-encoded responses, using standard HTTP response codes which should make our API familiar to anyone with previous experience using APIs.

From this point on and using this documentation as a guide, you should be able to integrate and test calls for:

  • Creating natural and legal type users. (see USERS)
  • Creating wallets for each user you create. This option will be useful if you are going to integrate pre-funded credit type cards or if you want to manage more than one wallet per user. (see WALLETS)
  • Managing balances of wallets created through PayIns, PayOuts, and transfers between wallets. (see WALLET OPERATIONS)
  • Creating cards linked to the created wallets. (see CARDS)
  • Managing created cards. (see CARD OPERATIONS)
It is important to highlight that the creation cards has different endpoints for debit, credit, and prepaid cards. In the initial exploration, our commercial team must have assigned you the specific details of the profiles of your card program, which will define to which endpoint(s) you should make calls for the creation of your cards, as well as a unique code for your assigned profile that should be included in the card creation calls.

Sandbox Access and Auth

To start an integration process, you must first request integration API Keys by contacting (email address for this purpose). The API keys will be delivered via email to the technical responsible party.

Handling the keys is of great importance and it is the responsibility of the key recipient to keep them safe. Secret keys must not be shared on any publicly accessible site such as GitHub, client-side code, etc.

Authentication to the API should be performed via X-API Key. It is necessary to provide the API Key as the basic user value, without the need to provide a password.

All calls must be made via HTTPS; any call made via HTTP or without authentication will fail.

With the integration credentials, you will be able to make calls to the NeoBank API testing environment directly. Our team will provide tools to test the endpoints as you develop your code towards our environments (you can choose between Swagger or Postman).

Entity Structure

The NeoBank API has 3 fundamental entities with which you will interact each time you consume an endpoint to complete the various available flows. These entities identify the end users of the card issuance service, the wallets or virtual containers for money, and the cards associated with them.

A diagram of PayCaddy's core entities and their relationships to each other

UserID:
Uniquely identifies an EndUser or MerchantUser interchangeably. The UserID is the primary entity of the NeoBank API. The process of creating an EndUser or MerchantUser always results in the creation of a UserID and, in turn, an associated WalletID.

WalletID:
The WalletID is the identifier of the electronic money container to which funds are credited and debited through PayIns, PayOuts, and/or transactions of the card(s) associated with it. A UserID will always be associated with at least one WalletID; however, it may contain multiple WalletIDs if required by the client's solution.

CardID:
These are the unique identifiers of the card that also serve as an abstraction of the PAN of the issued cards, avoiding the need for storing sensitive card information.

Flows Overview

The flows for using the NeoBank API are categorized based on the main entity they register, modify, or query. At a high level, the flows are correlated as explained bellow:

Paycaddy endpoint usage flow. Use our services in this order and with this architecture in mind

User Flow

The creation of new UserIDs in the NeoBank API follows two separate flows depending on the type of person to be entered into the system.

EndUser refers to the users created for natural persons.
MerchantUser refers to the users created for legal entities.

It is important to note that there are separate endpoints for creating EndUsers and MerchantUsers.

During the initial exploration, our sales team should have assigned you the specific details of your card program profiles, which will define which endpoint(s) you should call for user creation and the relevant KYC obligations.
Verification flow for the different types of user you can create in PayCaddy's API

Card Flow

The NeoBank API has differentiated calls for the creation of debit, credit, and prepaid cards. Through these calls, it is possible to create a physical or virtual card for an existing UserID linked to the available balance in a specific WalletID of that user.

All cards are created using a unique parameterization code for each card product, which must be previously requested from the PayCaddy integration team.

The creation of a card starts with the post debitCard POST, creditCard POST or prepaidCard POST call, depending on the acquired issuance service.

It is important to consider the type of user for which the card has been parameterized. Cards parameterized for natural persons can only be created by associating them with UserIDs representing EndUsers, while those parameterized for legal entities can only be created by associating them with MerchantUsers.

Once you have been granted a card creation code, you can begin testing card creation in the test environment.

Overarching flow for the creation and activation of a card in PayCaddy's API.

Credit Flow

For credit card issuance programs that use credit lines, the endpoints below will be used to manage the funds made available in the wallets associated with each credit line.

If the cards are prepaid credit, please see the wallet POST endpoint to create wallets that have the ability to create credit cards.

The credit operation follows the flow below and uses the endpoints detailed in this section.

Credit wallet creation flow.

Table of Contents

OverviewUsersCardsCredit

EndUser - Natural Person

EndUser POST

Request URL: https://api.paycaddy.dev/v1/endUsers

The creation of a new user for a natural person begins with a POST call in which an endpoint is consumed for sending the user's basic information:

{
 "email": "string",
 "firstName": "string",
 "lastName": "string",
 "occupation": "string",
 "placeofwork": "string",
 "pep": "bool",
 "salary": "integer",
 "telephone": "string",
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 }
}

{
 "id": "string",
 "firstName": "string",
 "lastName": "string",
 "email": "string",
 "telephone": "string",
 "placeOfWork": "string",
 "pep": true,
 "salary": 0,
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 },
 "isActive": false,
 "walletId": "string",
 "kycUrl": "string",
 "creationDate": "2022-07-13T21:07:21.166Z"
}

It should be noted that the responsibility for validating the accuracy and format of the entered data falls on the PayCaddy client, meaning that our API will return a successful response as long as the following parameters are met, regardless of the accuracy of the information or duplication of the shared data:

  1. The First Name and Last Name fields must add up to a maximum total of 22 characters that must be sent in a sanitized form, removing special characters and limiting themselves to the ASCII range.
  2. None of the fields should be sent as NULL.
  3. The email field must follow a standard email format.

In addition to the format verifications, it is important to highlight the responsibility of the client to consistently send the remaining fields with correct information:

  1. The "salary" field should include the user's monthly salary in USD.
  2. The "pep" field indicates whether the natural person for whom the user is being created is politically exposed.

PEP: Someone who has been entrusted with a prominent public responsibility. Typically, a PEP presents a higher risk of potential involvement in bribery and corruption by virtue of their position and influence.

The control over user duplication must be managed by the PayCaddy client. Our API will generate multiple distinct userIds regardless of whether the shared data is identical in duplicate calls.

If this event does not generate errors, the system will respond with an HTTP 200 OK message. The successful response replicates the entered data and adds information about the isActive parameters and the initial walletId associated with the userId, as well as loading a timestamp of the creation date of said user.

If there is an error, the system will respond with one of the following error messages with status code 400:

{
 "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
 "title": "One or more validation errors occurred.",
 "status": 400,
 "traceId": "00-68857a5c83b83b498f4c49d8a61d91cb-1a140dcbf259a24d-00",
 "errors": {
   "FirstName": [
     "The FirstName field is required."
   ]
 }
}

{
"type": "",
"title": "The value provided for the name exceeds the maximum value",
"status": 0,
"detail": "",
"instance": ""
}

{
 "type": "",
 "title": "Invalid format for email",
 "status": 0,
 "detail": "",
 "instance": ""
}

In case you encounter an error message 500, this could indicate an internal server error in the system. If you face this situation, we ask that you inform the PayCaddy team so that we can investigate and solve the problem efficiently.

Once the user and wallet identifiers have been assigned, the end-user must complete the KYC verification in order to complete the profile creation procedure. Until this verification is completed, the "isActive" control field will remain assigned as false, disabling any procedures.

In the user creation response (EndUser POST), a link to the identity validation associated with the userId in Metamap is presented, where the instructions and steps to follow will be presented to the end-user to complete the verification.

{
 "id": "string",
 "firstName": "string",
 "lastName": "string",
 "email": "string",
 "telephone": "string",
 "placeOfWork": "string",
 "pep": true,
 "salary": 0,
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 },
 "isActive": false,
 "walletId": "string",
 "kycUrl": "https%3a%2f%2fsignup.getmati.com%2f%3fmerchantToken%
3d6046cc2a54816f001bedd641%26flowId%3d6046cc2a54816f0
01bedd640%26metadata%3d%7b%22userid%22%3a%226955ea0f4
f3-4254-b10a-0181f307298c%22%7d",

 "creationDate": "2022-07-12T15:29:01.8271862+00:00"
}

It is important to consider that the kycURL is shared by applying URL encoding that allows the sending of metadata (userId) that links the validation with the created user. To ensure the activation of the user upon successfully completing the validation, it is necessary to ensure that the URL to which the user is redirected from the front-end interface loads the following structure:

https://signup.getmati.com/?merchantToken=6046cc2a54816f001dedd641&
flowId=6046cc2a54816f001bedd640&
metadata={"userid":"a955ea0f-34f3-4254-b10a-0181f30729kd"}

For complete information on KYC, please find detailed information on this documentation's KYC chapter

EndUser GET

Request URL: https://api.paycaddy.dev/v1/endUsers/

The GET call for an endUser allows you to know the stored data of a particular userId, especially the walletId of their initial wallet and the activity status of this user in the "isActive" field. Both data are crucial for the other calls to the NeoBank API.

This call can be used to verify the user's status at any point in the flow.

https://api.paycaddy.dev/v1/endUsers/5bcf7be1-717c-49ed-a8a4-0170892308ab

//Response - 200
{
 "id": "string",
 "firstName": "string",
 "lastName": "string",
 "email": "string",
 "telephone": "string",
 "placeOfWork": "string",
 "pep": true,
 "salary": 0,
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 },
 "isActive": true,
 "walletId": "string",
 "kycUrl": "string",
 "creationDate": "2023-03-22T19:13:46.178Z"
}

MerchantUser - Legal Person

MerchantUser POST

Request URL: https://api.paycaddy.dev/v1/merchantUsers

The creation of a new user for a legal entity begins with a POST call in which an endpoint is consumed for sending the basic data of the legal entity.

{
 "email": "string",
 "registeredName": "string",
 "numOfRegistration": "string",
 "ruc": "string",
 "kindOfBusiness": "string",
 "telephone": "string",
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 }
}

{
 "id": "string",
 "email": "string",
 "registeredName": "string",
 "numOfRegistration": "string",
 "ruc": "string",
 "kindOfBusiness": "string",
 "telephone": "string",
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 },
 "isActive": true,
 "walletId": "string",
 "creationDate": "2022-07-18T22:29:45.914Z"
}

It should be noted that the responsibility for validating the accuracy and format of the entered data falls on the PayCaddy client, meaning that our API will return a successful response as long as the following parameters are met, regardless of the accuracy of the information or duplication of the shared data:

  1. The First Name and Last Name fields must add up to a maximum total of 22 characters that must be sent in a sanitized form, removing special characters and limiting themselves to the ASCII range.
  2. None of the fields should be sent as NULL.
  3. The email field must follow a standard email format.

In addition to the format verifications, it is important to highlight the responsibility of the client to consistently send the remaining fields with correct information:

  1. The field "RUC" must include the number of the Unique Taxpayer Registry or its international counterpart for tax identification such as VATIN, CUIT, CNPJ, NIT, or RUT.
  2. The "numOfRegistration" field must include the registration number of the legal entity as determined by the institution. This field can replicate the data from "RUC" in case the information is not applicable in your jurisdiction.
  3. The "kindOfBusiness" field should enter a brief description of the economic activity performed by the legal entity. The NeoBank API does not validate the detailed information provided in this field; however, it is crucial to ensure the submission of accurate information as it will be used by the compliance team in evaluating the user.

If this event does not generate errors, the system will respond with an HTTP 200 OK message. The successful response replicates the entered data and adds information about the isActive parameters and the initial walletId associated with the userId, as well as loading a timestamp of the creation date of said user.

Controls for user duplication must be managed by integrating partners. Our API will generate multiple distinct userIds, regardless of whether the shared data is identical in duplicate calls.

If there is an error, the system will respond with one of the following error messages with status code 400:

{
 "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
 "title": "One or more validation errors occurred.",
 "status": 400,
 "traceId": "00-68857a5c83b83b498f4c49d8a61d91cb-1a140dcbf259a24d-00",
 "errors": {
   "FirstName": [
     "The FirstName field is required."
   ]
 }
}

{
"type": "",
"title": "The value provided for the name exceeds the maximum value",
"status": 0,
"detail": "",
"instance": ""
}

{
 "type": "",
 "title": "Invalid format for email",
 "status": 0,
 "detail": "",
 "instance": ""
}

In case you encounter an error message 500, this could indicate an internal server error in the system. If you face this situation, we ask that you inform the PayCaddy team so that we can investigate and solve the problem efficiently.

MerchantUser GET

Request URL: https://api.paycaddy.dev/v1/merchantUsers/

The GET call for a merchantUser allows you to know the stored data of a particular userId, especially the walletId of their initial wallet and the activity status of this user in the "isActive" field. Both data are crucial for the other calls to the NeoBank API.

This call can be used to verify the user's status at any point in the flow.

https://api.paycaddy.dev/v1/merchantUsers/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "id": "string",
 "email": "string",
 "registeredName": "string",
 "numOfRegistration": "string",
 "ruc": "string",
 "kindOfBusiness": "string",
 "telephone": "string",
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 },
 "isActive": true,
 "walletId": "string",
 "creationDate": "2022-07-18T22:29:45.914Z"
}

EndUserSR - Delegated KYC Flow

EndUserSR POST

Request URL: https://api.paycaddy.dev/v1/SR/endUserSRs/

The creation of a new user for a natural person with a delegated KYC flow begins with a POST call in which an endpoint is consumed for sending the basic data of the user:

{
 "email": "string",
 "firstName": "string",
 "lastName": "string",
 "occupation": "string",
 "placeofwork": "string",
 "pep": "bool",
 "salary": "integer",
 "telephone": "string",
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string",
}
"idUrlFront": "string",
"idUrlBack": "string",
"residenceProofUrl": "string",
}

{
 "id": "string",
 "firstName": "string",
 "lastName": "string",
 "email": "string",
 "telephone": "string",
 "placeOfWork": "string",
 "pep": true,
 "salary": 0,
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
"homeNumber" : "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 },
 "isActive": true,
 "walletId": "string",
 "idUrlFront": "string",
"idUrlBack": "string",
"residenceProofUrl": "string",
 "creationDate": "2022-07-13T21:07:21.166Z"
}

The fields "idUrlFront", "idUrlBack", and "residenceProofUrl" must be sent with unique URLs where images of the front and back of the user's national identity card and a proof of residence are stored. The specific parameters for uploading these documents must have been previously agreed with the compliance department of PayCaddy.

Users created under this flow are born with an active status but are subject to blockages in case the KYC information sent in the creation call is rejected by the compliance team of PayCaddy.

It should be noted that the responsibility for validating the accuracy and format of the entered data falls on the PayCaddy client, meaning that our API will return a successful response as long as the following parameters are met, regardless of the accuracy of the information or duplication of the shared data:

  1. The First Name and Last Name fields must add up to a maximum total of 22 characters that must be sent in a sanitized form, removing special characters and limiting themselves to the ASCII range.
  2. None of the fields should be sent as NULL.
  3. The email field must follow a standard email format.

In addition to the format verifications, it is important to highlight the responsibility of the client to consistently send the remaining fields with correct information:

  1. The "salary" field should include the user's monthly salary in USD.
  2. The "pep" field indicates whether the natural person for whom the user is being created is politically exposed.

PEP: Someone who has been entrusted with a prominent public responsibility. Typically, a PEP presents a higher risk of potential involvement in bribery and corruption by virtue of their position and influence.

The control over user duplication must be managed by the PayCaddy client. Our API will generate multiple distinct userIds regardless of whether the shared data is identical in duplicate calls.

If this event does not generate errors, the system will respond with an HTTP 200 OK message. The successful response replicates the entered data and adds information about the isActive parameters and the initial walletId associated with the userId, as well as loading a timestamp of the creation date of said user.

Wallets

Wallets POST

Request URL: https://api.paycaddy.dev/v1/wallets

The creation of a wallet is done through a POST call that carries the following structure::

{
 "userId": "string",
 "currency": "string",
 "description": "string",
 "walletType": 0
}

{
 "id": "string",
 "userId": "string",
 "currency": "string",
 "description": "string",
 "balance": 0,
 "amountWithheld": 0,
 "creationDate": "2022-07-19T20:08:29.970Z"
}

This call must be made by associating it with a previously created active userId.

The currency field must consider the codes of ISO 4217. (e.g. US Dollars would be entered with the code "USD").

The description field is created to name the wallet created according to the intended use.

The "walletType" field defines whether the wallet can or cannot be associated with a credit card (see creditCard POST). This boolean must be kept as "0" for all wallets created for debit cards, prepaid cards, or for fund and transfer management. For wallets created for prefunded credit type cards, the "walletType" must be defined as "1".

The "Main Wallets" created automatically in the user creation flow maintain a "walletType" of "0".

In case there is an error in the call, the NeoBank API will respond with an HTTP 400 error with the error description.

In case of encountering an HTTP 500 error, please contact PayCaddy support team with the incident description.

Wallet GET

Request URL: https://api.paycaddy.dev/v1/wallets/

https://api.paycaddy.dev/v1/wallets/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "id": "string",
 "userId": "string",
 "currency": "string",
 "description": "string",
 "balance": 0,
 "amountWithheld": 0,
 "creationDate": "2022-07-19T20:08:29.970Z"
}

The GET call for wallets allows you to retrieve the information associated with the queried walletId. This call is particularly important for checking the available balance in a wallet and the balance withheld due to pending transactions.

The total balance is reflected in the "balance" field of the successful 200 response to this call, while the balance withheld is reflected in the "amountWithheld" field.

All amounts are reflected in cents, meaning USD 1,000.00 would be represented as 100000.

The call may fail if an incorrect walletId is provided, in which case the NeoBank API would respond with a HTTP 400 error.

{
 "type": "",
 "title": "Wallet 'c4d165d1-721d-4d78-a48d-017f0c6facf8' not found",
 "status": 0,
 "detail": "",
 "instance": ""
}

WalletsPerUserId POST

Request URL: https://api.paycaddy.dev/v1/WalletsPerUserIds

This endpoint allows retrieving all the wallets associated with a user ID.
By making a POST request with the user's ID, the system returns a list of the identifiers of the different wallets that the user has.

{
 "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{  
"walletsJson": "[
{\"Id\":\"216fa217-6826-48b8-ab5b-0180891cef30\",\"BDateUtcCreate\":\"2022-05-03T08:50:16.4959966\",\"BTimestamp\":\"AAAAAAAb6Pk=\",
\"ClientId\":\"1c5a29f5-b018-40c7-a6d4-017efe423d42\",\"UserId\":\"qa2c3b2a-23f6-49be-b882-0180891cef30\",\"Currency\":\"USD\",\"Description\":\"Main wallet\",\"AmountAvailable\":38574,\"AmountWithheld\":1110756}
,
{\"Id\":\"d6928675-a4fe-4752-8e7e-018099d30fe1\",\"BDateUtcCreate\":\"2022-05-06T14:43:07.7804616\",\"BTimestamp\":\"AAAAAAAbv6Q=\",
\"ClientId\":\"1c5a29f5-b018-40c7-a6d4-017efe423d42\",\"UserId\":\"ea2c3b2a-23f6-49be-b882-0180891cef30\",\"Currency\":\"USD\",\"Description\":
\"SecondaryWallet\",\"AmountAvailable\":381599,
\"AmountWithheld\":29253372}

]"}

The response to this call carries all the information from the multiple wallets associated to the same UserId in a string format that maintains the same structure as the response of the Wallet GET call.

Credit Wallets

Wallet Credit POST

Request URL: https://api.paycaddy.dev/v1/walletCredits/

The creation of a credit wallet is done through the POST call that carries the following structure:

{
 "userId": "string",
 "currency": "string",
 "description": "string",
 "time": 0,
 "limit": 0
}

{
 "id": "string",
 "userId": "string",
 "currency": "string",
 "description": "string",
 "limit": 0,
 "creationDate": "2023-01-17T10:11:42.287Z"
}

This call must be made by associating it with a previously created active userId.

The currency field must consider ISO 4217 codes. (For example, US Dollars would be entered with the code "USD").

The "description" field is used to name the wallet according to its intended use, but is not mandatory for creating a new wallet.

The "time" field defines the number of days that the credit line must remain active. This field is used to define the term of a revolving credit (see ReportPayCredit).

Finally, the "limit" field sets the credit limit amount in cents that the wallet will have.

Wallet Credit GET

Request URL: https://api.paycaddy.dev/v1/walletCredits/

The creation of a credit wallet is done through the POST call that carries the following structure:

{
 "userId": "string",
 "currency": "string",
 "description": "string",
 "time": 0,
 "limit": 0
}

{
 "id": "string",
 "userId": "string",
 "currency": "string",
 "description": "string",
 "limit": 0,
 "creationDate": "2023-01-17T10:11:42.287Z"
}

This call must be made by associating it with a previously created active userId.

The currency field must consider ISO 4217 codes. (For example, US Dollars would be entered with the code "USD").

The "description" field is used to name the wallet according to its intended use, but is not mandatory for creating a new wallet.

The "time" field defines the number of days that the credit line must remain active. This field is used to define the term of a revolving credit (see ReportPayCredit).

Finally, the "limit" field sets the credit limit amount in cents that the wallet will have.

Credit Operations

ReportPayCredit POST

Request URL: https://api.paycaddy.dev/v1/reportPayCredits

To restore revolving credit lines, the ReportPayCredit endpoint is used. Users who have an active credit must make the corresponding payments in order to restore credit.

The call to report payments is made using the following structure:

{
 "walletId": GUID,
 "amountToCapital": 0,
 "amountInterest": 0,
 "currency": "string",
 "statement": "string",
 "restoreCredit": true
}

{
 "creationDate": "2023-01-16T16:22:39.975Z",
 "limit": "string",
 "amountAvailable": "string"
}

This call is responsible for making a payment to restore credit for the wallet associated with the walletId passed as a parameter.

This method must be performed periodically by the user, taking into account the characteristics established at the time of creating the credit wallet (see UtcCreateLastPayment in CreditWallet).

The field called 'amountToCapital' determines the amount that the user is reporting, which will have an impact on the available amount and the amount owed by the user within the credit line.

The 'currency' field corresponds to the currency of the wallet. The 'statement' field will be used to leave a brief description of the operation performed, and finally, the 'restoreCredit' field provides a boolean functionality to restore operability to blocked credit lines.

The 'amountToInterest' field is optional to keep a log of the interest generated by the credit line associated with a walletId.

If successful, the payment report will be generated with the specified data, and the call will return an HTTP 200 detailing the date on which the report was made, as well as the values of the card limit and the available balance.

If there is an error in the call, the NeoBank API will respond with a HTTP 400 error. The most common errors may include:

  • Invalid walletId.
  • Currency value does not match the original currency of the wallet.

ChangeWalletLimit POST

Request URL: https://api.paycaddy.dev/v1/walletCredits/changeWalletLimit

This method will be used to modify the limits previously established in the credit wallets of PayCaddy API users. The limits may vary to increase or decrease the limit, depending on the reason for executing the method.

{
 "walletId": "string",
 "newLimit": 0,
 "currency": "string",
 "statement": "string"
}

{
 "walletId": "string",
 "newLimit": 0
}

The call will be associated with the provided 'walletId', followed by the value entered in the 'newLimit' field, which will represent the amount that needs to be updated in the 'limit' property of the wallet.

The 'currency' field must correspond to the 'currency' property of the indicated wallet, and finally, the 'statement' field provides a brief description of the operation performed.

All amounts are reflected in cents, meaning USD 1,000.00 would be represented as 100000.

The call may fail if an incorrect walletId is provided, in which case the PayCaddy API would respond with a HTTP 400 error.

CheckCreditOperation GET

Request URL: https://api.paycaddy.dev/v1/CheckCredit

The CheckCreditOperation GET call allows for retrieving information about a queried 'walletId'. This call is especially important for checking the activity status of the wallet.

If successful, the call will return an HTTP 200 detailing the associated 'walletId' and the status of the wallet."

https://api.paycaddy.dev/v1/CheckCredit/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "walletId": "string",
 "status": "string"
}

The value of the 'status' attribute can be:

True if the wallet is activated and available for transactions.
False if it is blocked, either by the system or due to non-payment (see 'reportPayCredit').

Wallet Operations

PayIn POST

Request Url: https://api.paycaddy.dev/v1/payIns

PayIn is PayCaddy API's method for adding funds to a specific wallet. It is a simple call that loads the information of the 'walletId' to which funds are to be loaded, the amount to be credited to the wallet in cents, the code of the currency according to ISO 4217, and a description of the transaction.

{
 "walletIdTo": "string",
 "amount": 0,
 "currency": "string",
 "statement": "string"
}

{
 "id": "string",
 "walletIdTo": "string",
 "amount": 0,
 "currency": "string",
 "statement": "string",
 "creationDate": "2022-07-20T20:47:04.060Z"
}

The successful response of this call, in addition to the provided information, includes a timestamp with the execution date of the transaction and a unique transaction identifier that allows retrieving the associated information with the GET call.

If there is a problem with the data provided the PayCaddy API will respond with a HTTP 400 error.

{
 "type": "Decoding body",
 "title": "Error ",
 "status": 422,
 "detail": "Wallet not found",
 "instance": ""
}

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

PayIn GET

Request URL: Request URL: https://api.paycaddy.dev/v1/payIns/

The GET call for a PayIn allows accessing information related to a specific transactionId. The successful response of this call loads the following structure:

https://api.paycaddy.dev/v1/payIns/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "data": [
   {
     "id": "string",
     "walletIdTo": "string",
     "amount": 0,
     "currency": "string",
     "statement": "string",
     "creationDate": "2022-07-20T20:47:04.056Z"
   }
 ]
}

The call may fail if an incorrect walletId is provided, in which case the PayCaddy API would respond with a HTTP 400 error.

PayOut POST

Request URL: https://api.paycaddy.dev/v1/payOuts

PayOut is a method to debit funds available in a specific wallet. Unlike a transfer, using this method eliminates the existence of the funds from the NeoBank API. This method should be associated with an accounting operation that requires such a call.

Similar to PayIn, the successful response will return the entered data accompanied by a unique transaction identifier and its timestamp.

{
 "walletIdFrom": "string",
 "amount": 0,
 "currency": "string",
 "statement": "string"
}

{
 "id": "string",
 "walletIdFrom": "string",
 "amount": 0,
 "currency": "string",
 "statement": "string",
 "creationDate": "2022-07-20T20:47:04.060Z"
}

If there is a problem with the data provided the PayCaddy API will respond with a HTTP 400 error.

{
 "type": "Decoding body",
 "title": "Error ",
 "status": 422,
 "detail": "Wallet not found",
 "instance": ""
}

The API will respond with the same error as if wallet was not found if the walletId is associated with a blocked user.

It is recommended to verify the status of the user associated with the walletId to which funds are to be credited prior to making the PayOut POST call.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

{
 "type": "",
 "title": "Wallet does not have sufficient funds",
 "status": 0,
 "detail": "",
 "instance": ""
}

PayOut GET

Request URL: https://api.paycaddy.dev/v1/payOuts/

The GET call for a PayOut allows access to information related to a specific transactionId. The successful response of this call loads the following structure:

https://api.paycaddy.dev/v1/payOuts/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "data": [
   {
     "id": "string",
     "walletIdTo": "string",
     "amount": 0,
     "currency": "string",
     "statement": "string",
     "creationDate": "2022-07-20T20:47:04.056Z"
   }
 ]
}

The API will respond with an HTTP 400 error if it is an incorrect transactionId or a transactionId that is not related to a PayOut.

Transfer POST

Request URL: https://api.paycaddy.dev/v1/transfers

To carry out transactions within the NeoBank API environment between two previously created wallets, the Transfer POST call must be used, which has the following structure:

{
 "walletIdFrom": "string",
 "walletIdTo": "string",
 "amount": 0,
 "currency": "string",
 "statement": "string"
}

{
 "id": "string",
 "walletIdFrom": "string",
 "walletIdTo": "string",
 "amount": 0,
 "currency": "string",
 "statement": "string",
 "creationDate": "2022-07-22T15:54:08.059Z"
}

In this call, you must specify the walletId from which the funds are being sent and the walletId to which the funds are being sent. The "currency" field must load the code of the currency associated with both wallets following the ISO 4217 standard.

The PayCaddy API does not manage currency conversions, so it is necessary to consider that both wallets must be configured under the same currency.

The amount entered in the "amount" field must be in cents following the standard of the other PayCaddy API calls.

The "statement" field allows you to enter a description of the transaction for future reference and display on the front-end.

The successful response to this call loads a unique transaction identifier and the timestamp of its acceptance.

In case of an error in the call, the NeoBank API will respond with a descriptive HTTP 400 error.

Commonly, the call will fail if the walletIds involved in the transaction belong to an inactive userId, that is, maintaining its "isActive" attribute as "false".

Similarly, the call will always fail if the walletIdFrom does not maintain the adequate balance to cover the transaction or when the currency code of both wallets is not the same as the transfer POST call.

Transfer GET

Request URL: https://api.paycaddy.dev/v1/transfers/

The GET call for a transfer between wallets allows access to information related to a specific transactionId and carries the following structure:

https://api.paycaddy.dev/v1/transfers/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "data": [
   {
     "id": "string",
     "walletIdFrom": "string",
     "walletIdTo": "string",
     "amount": 0,
     "currency": "string",
     "statement": "string",
     "creationDate": "2022-07-22T16:07:33.092Z"
   }
 ]
}

The API will respond with a descriptive HTTP 400 error if an incorrect transaction ID is provided or if the transaction ID is not related to a transfer.

TransactionDetailList POST

Request URL: https://api.paycaddy.dev/v1/TransactionDetailList

This POST call retrieves all transactions of a particular cardId provided.

{
 "cardId": "904ee16a-db84-4120-9714-0180892341b3",
 "startDate": "2023-01-23T18:21:02.157Z"
}

{
 "transactionListJson": "[{\"c1Tipo\":\"PeticionAutorizacion\",\"c2CardId\":\"904ee16a-db84-4120-9714-0180892341b3\",\"c3CodigoProceso\":\"000000\",\"c4ImporteTrans
accion\":\"116\",\"c7FechaHoraTransaccion\":\"20230203194512\"
,\"c11NumeroIdentificativoTransaccion\":\"000088058\",\"c18Cod
igoActividadEstablecimiento\":\"4111\",\"c19CodigoPaisAdquiren
te\":\"724\",\"c38NumeroAutorizacion\":\"169\",\"c41TerminalId
\":\"00004001\",\"c42Comercio\":\"000000047219191\",\"c43Ident
ificadorComercio\":\"TRANVIA DE MURCIA        CHURRA-MURCIA  
         \"},{\"c1Tipo\":\"PeticionAutorizacion\",\"c2CardId\":\"904ee16a-db84-4120-9714-0180892341b3\",\"c3CodigoProceso\":\"000000\",\"c4ImporteTrans
accion\":\"2266\",\"c7FechaHoraTransaccion\":\"20230317135513\
",\"c11NumeroIdentificativoTransaccion\":\"000099870\",\"c18Co
digoActividadEstablecimiento\":\"5813\",\"c19CodigoPaisAdquire
nte\":\"724\",\"c38NumeroAutorizacion\":\"171\",\"c41TerminalI
d\":\"90315259\",\"c42Comercio\":\"000000175240563\",\"c43Iden
tificadorComercio\":\"BULEVAR CAFE EL RANERO   MURCIA
                  \"}]"
}

The structure of the data shared in each transaction follow the same format as all transaction notifications. (See Transaction Webhooks).

TransactionDetailListByWallet POST

Request URL: https://api.paycaddy.dev/v1/TransactionDetailListByWallet

The TransactionDetailListByWallet endpoint offers a detailed view of all transactions linked to a specific wallet. This encompasses wallet-specific transactions like pay-ins, pay-outs, and transfers, as well as card transactions tied to the specified wallet ID.

{
 "walletId": "Your Wallet ID",
 "startDate": "Start Date in ISO Format",
 "toDate": "End Date in ISO Format",
 "maxTransactions": "Maximum Number of Transactions",
 "offset": "Number of Transactions to Skip",
 "c43IdentificadorComercio": "Optional Merchant Identifier Filter"
}

{
 "transactionListJson": "[{transaction1},{transaction2},...,{transactionN}]",
 "totalItems": "Total number of transactions within the requested date range",
 "currentPage": "Current page number indicator",
 "totalPages": "Total number of pages available"
}

Each card transaction in the response payload will be a stringified version of the Transaction Notification Webhooks, augmented with three additional field:

{
"c1Tipo": "string",
"c2CardId": "string",
"c3CodigoProceso": "string",
"c4ImporteTransaccion": "string",
"c7FechaHoraTransaccion": "string", // in yyyyMMddHHmmss format
"c11NumeroIdentificativoTransaccion": "string",
"c18CodigoActividadEstablecimiento": "string",
"c19CodigoPaisAdquirente": "string",
"c38NumeroAutorizacion": "string",
"c41TerminalId": "string",
"c42Comercio": "string",
"c43IdentificadorComercio": "string",
"c51MonedaImporteTransaccion": "string",
"c6ImporteMonedaTransaccion": "string",
"isSettled": "true"

}

  • c51MonedaImporteTransaccion: Represents the currency used for the transaction at the POS.
  • c6ImporteMonedaTransaccion: Denotes the transaction amount in the currency used at the POS.
  • isSettled: Indicates the settlement status of a transaction. A value of "false" signifies transactions that are unsettled or in transit, while "true" indicates transactions that have been settled.

Since PayCaddy abstracts the settlement process for its clients, this field is particularly pertinent to specific use cases like reversals and offline cancellations.

The retrieved transaction list will encompass all transactions with "c1tipo" transaction types impacting the wallet's balance. Additional "c1tipo" such as denied transactions won't be included.

Transactions from the Batch Process with "c1tipo" values of "transaccionCorregidaNegativa" and "transaccionCorregidaPositiva" will be incorporated in the retrieved list, aligning with the expected logic in the webhooks.

Each wallet transaction will be presented in their standard 200 response payload:

Parameters Explanation:

Request:

  • walletId: The unique ID for the wallet, essential for fetching associated transactions.
  • startDate & toDate: Set the date range for transaction retrieval. To fetch and paginate all transactions, use the current date for both fields.
  • maxTransactions: Determines the maximum transactions to be returned. If more transactions exist within the date range, they'll be excluded.
  • offset: Sets the starting point for transactions, fetched in reverse chronological order, facilitating pagination.
  • c43IdentificadorComercio: An optional filter based on a specific merchant. For instance, "UBER" fetches all transactions with "UBER" in their merchant identifier.

Response:

  • transactionListJson: Contains a stringified JSON of all requested transactions in reverse chronological order.
  • totalItems: Specifies the total transactions in the transactionListJson.
  • currentPage: Indicates the current page based on totalItems and the request's offset.
  • totalPages: Shows the total pages based on totalItems and the request's maxTransactions.

Pagination:

To manage pagination, adjust the maxTransactions and offset parameters in your request. This ensures a controlled exploration of historical transactions, maintaining a swift UX/UI performance.

The currentPage and totalPages parameters are included in each response for convenience, both calculated based on the totalItems and offset parameters.

For instance, with a totalItems of "25" and an offset of "125", the currentPage would be "6", displaying transactions numbered 126 to 150 from the date range in reverse chronological order.

ChargebackOperation POST

Request URL: https://api.paycaddy.dev/v1/ChargeBackOperation

This endpoint allows marking a specific transaction associated with a card to be studied by a team of chargeback specialists. By requesting the analysis of a chargeback, the team will evaluate whether the transaction can be reversed and the funds returned to the cardholder.

{
 "numeroidentificativoTransaction": "string",
 "cardId": "string"
}

{
 "TransactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "IsChargeBack": true,
 "ChargeBackStatus": "string"
}

Once the transaction is marked, the state and updates of the chargeback will be notified to clients through the chargeback webhook. (See Webhooks)

Change Internal Wallet Limit POST

Request URL: https://api.paycaddy.dev/v1/ChangeLimitIWL

Each card generated by PayCaddy's API has a series of properties that are used when conducting transactions. One of these is the limit assigned by clients to control the spending of their users. The value of the limit will determine the amount that can be transacted and may vary for each user. Only clients can make changes and updates to the limit value.

The limits are reset at the beginning of each month, and each transaction is approved according to the current limit at the time.

{
   "cardId": "string",
   "limit": 0
}

{
   "cardId": "string",
   "limit": 0
}

The API will respond with a HTTP 422 Error "card not found" if the provided cardId has no match for the authenticated client.

Internal Wallet Limit GET

Request URL: https://api.paycaddy.dev/v1/ChangeLimitIWL

To retrieve the current limit of a particular card the GET method for the Internal Wallet Limit must be used.

The request must be made with the particular cardId that is to be consulted. In the example below, the cardId is highlighted in the request URL.

https://api.paycaddy.dev/v1/ChangeLimitIWL/3fa85f64-5717-4562-b3fc-2c963f66afa6

{
   "cardId": "string",
   "limit": 0
}

In case the Limit is 0 or has not been previously set, the response will carry a message of “No stablish internal limit” as the limit attribute.

The API will respond with a HTTP 422 Error "card not found" if the provided cardId has no match for the authenticated client.

Debit Cards

DebitCard POST

Request URL: https://api.paycaddy.dev/v1/debitCards

This call enables the creation of a Debit Card and follows the following structure:

{
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string"
}

{
 "id": "string",
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string",
 "isActive": true,
 "status": "string",
 "creationDate": "2022-08-01T19:37:50.392Z",
 "dueDate": 0
}

Each request includes the userId to whom the card should be associated and the walletId whose balance the card will be transacting with.

The physicalCard field indicates whether it is a card that needs to be printed physically (true) or, alternatively, an exclusively digital card (false).

The card printing data is extracted from the fields stored in the user creation, so it is important to note that the cards are printed taking into account the FirstName and LastName fields in the case of natural persons and the RegisteredName field in the case of legal entities. It is essential to ensure the integrity of these fields in the user creation flow, including character limitations, since it affects the subsequent card creation flow.

The "code" sent in the call must be provided by the PayCaddy team for each type and variation of card included in the enablement project. That is, for a project that enables the issuance of a virtual or physical debit card for natural persons, two different codes would be provided, one for endUser physical and one for endUser virtual. It is the client's responsibility to correctly invoke the calls taking into consideration the type of user and the printing condition associated with the provided code.

The successful response of the debit card creation call returns a 200 message that carries the unique identifier of the card that must be used in all card operation calls (see cardOperations). In addition to the cardId, the 200 response also provides a boolean indicating whether the card is operational or not, and a status field describing the card's status.

The possible statuses are detailed below:

PendingAck - For newly created physical cards that have not been activated. (see AckReception POST)

Temporarilyblocked - For self-manageable blocks. (see UnblockCard POST)

Cancel - For canceled cards (see CancelCard POST)

Active - For active cards

The sensitive card data (PAN and CVV) can be queried using the checkPan POST and checkCvv POST calls. However, it is important to note that such data must NOT be stored in databases as they imply cybersecurity requirements associated with the PCI standard that have been abstracted with the use of the cardId in the PayCaddy API.

The card's expiration date is presented in the successful response of the card creation call in the "dueDate" field following the format YYYYMM.

In case of any error or inconsistency with the provided data, the API will respond with a descriptive 400 error of one of the most common possible reasons:

  1. The userId to which the card is to be associated does not exist or is inactive.
  2. The walletId to which the card is to be associated does not exist or does not belong to the entered user.
  3. The code provided in the call does not match the type of user to which the card is to be associated.
  4. The code provided in the call does not match the type of card (virtual or physical) being attempted to create.
It is important to note that retries in case of errors must be managed responsibly, i.e., by creating time limits of at least 5 seconds before the retry and limiting the number of retries to 3.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

DebitCard GET

Request URL: https://api.paycaddy.dev/v1/debitCards/

The GET call for debit cards allows you to query the data of a card based on a cardId.

https://api.paycaddy.dev/v1/debitCards/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "data": [
   {
     "id": "string",
     "userId": "string",
     "walletId": "string",
     "physicalCard": true,
     "code": "string",
     "isActive": true,
     "status": "string",
     "creationDate": "2022-08-01T21:57:16.932Z",
     "dueDate": 0
   }
 ]
}

This call is especially necessary in managing the transaction status of the card, since the successful response also includes the "isActive" boolean activity and the descriptive "status" field, in addition to the other fields in the successful response of card creation.In case an invalid cardId is sent, the PayCaddy API will respond with an HTTP 400 error.

If there is a HTTP 500 error encountered, report the incident to the PayCaddy support team.

Prepaid Cards

PrepaidCard POST

Request URL: https://api.paycaddy.dev/v1/prepaidCards

This is the call used to create Prepaid Cards associated with a particular userId and walletId, and it carries the following structure:

{
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string"
}

{
 "id": "string",
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string",
 "isActive": true,
 "status": "string",
 "creationDate": "2022-08-01T19:37:50.392Z",
 "dueDate": 0
}

Each request includes the userId to whom the card should be associated and the walletId whose balance the card will be transacting with.

The physicalCard field indicates whether it is a card that needs to be printed physically (true) or, alternatively, an exclusively digital card (false).

The card printing data is extracted from the fields stored in the user creation, so it is important to note that the cards are printed taking into account the FirstName and LastName fields in the case of natural persons and the RegisteredName field in the case of legal entities. It is essential to ensure the integrity of these fields in the user creation flow, including character limitations, since it affects the subsequent card creation flow.

The "code" sent in the call must be provided by the PayCaddy team for each type and variation of card included in the enablement project. That is, for a project that enables the issuance of a virtual or physical debit card for natural persons, two different codes would be provided, one for endUser physical and one for endUser virtual. It is the client's responsibility to correctly invoke the calls taking into consideration the type of user and the printing condition associated with the provided code.

The successful response of the debit card creation call returns a 200 message that carries the unique identifier of the card that must be used in all card operation calls (see cardOperations). In addition to the cardId, the 200 response also provides a boolean indicating whether the card is operational or not, and a status field describing the card's status.

The possible statuses are detailed below:

PendingAck - For newly created physical cards that have not been activated. (see AckReception POST)

Temporarilyblocked - For self-manageable blocks. (see UnblockCard POST)

Cancel - For canceled cards (see CancelCard POST)

Active - For active cards

The sensitive card data (PAN and CVV) can be queried using the checkPan POST and checkCvv POST calls. However, it is important to note that such data must NOT be stored in databases as they imply cybersecurity requirements associated with the PCI standard that have been abstracted with the use of the cardId in the PayCaddy API.

The card's expiration date is presented in the successful response of the card creation call in the "dueDate" field following the format YYYYMM.

In case of any error or inconsistency with the provided data, the API will respond with a descriptive 400 error of one of the most common possible reasons:

  1. The userId to which the card is to be associated does not exist or is inactive.
  2. The walletId to which the card is to be associated does not exist or does not belong to the entered user.
  3. The code provided in the call does not match the type of user to which the card is to be associated.
  4. The code provided in the call does not match the type of card (virtual or physical) being attempted to create.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

{
 "type": "",
 "title": "Wallet does not have sufficient funds",
 "status": 0,
 "detail": "",
 "instance": ""
}

It is important to note that retries in case of errors must be managed responsibly, i.e., by creating time limits of at least 5 seconds before the retry and limiting the number of retries to 3.

PrepaidCard GET

Request URL: https://api.paycaddy.dev/v1/prepaidCards/

The GET call for prepaid cards allows you to query the data of a card based on a cardId.

https://api.paycaddy.dev/v1/prepaidCards/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "data": [
   {
     "id": "string",
     "userId": "string",
     "walletId": "string",
     "physicalCard": true,
     "code": "string",
     "isActive": true,
     "status": "string",
     "creationDate": "2022-08-01T21:57:16.932Z",
     "dueDate": 0
   }
 ]
}

This call is especially necessary in managing the transaction status of the card, since the successful response also includes the "isActive" boolean activity and the descriptive "status" field, in addition to the other fields in the successful response of card creation.In case an invalid cardId is sent, the PayCaddy API will respond with an HTTP 400 error.

If there is a HTTP 500 error encountered, report the incident to the PayCaddy support team.


Credit Cards

CreditCard POST

Request URL: https://api.paycaddy.dev/v1/CreditCards

This call enables the creation of a Credit Card associated to a particular userId and walletId. The following structure must be kept to send the relevant data.

{
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string"
}

{
 "id": "string",
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string",
 "isActive": true,
 "status": "string",
 "creationDate": "2023-01-16T11:36:20.453Z",
 "dueDate": 0
}

In each call, the userId to which the card should be associated and the walletId with whose balance the card will be transacting are included.

For credit cards, the walletId to be associated must be a credit wallet (see WalletCredits) or a prepaid wallet with the "walletType" attribute equal to "1".

The physicalCard field indicates whether it is a card that should be printed physically true or, alternatively, an exclusively digital card false.

The card printing data is extracted from the fields stored in the user creation, so it is important to ensure that cards are printed taking into account the FirstName and LastName fields in the case of natural persons and RegisteredName in the case of legal persons. It is essential to ensure the integrity of these fields in the user creation flow, including character limitations, as this affects the subsequent card creation flow.

The code sent in the call must be provided by the PayCaddy team for each type and variation of card included in the enablement project, that is, for a project that enables the issuance of a virtual or physical credit card for natural persons, two different codes would be provided, one for endUser's physical and one for endUser's virtual. It is the client's responsibility to correctly invoke the calls taking into consideration the user type and printing condition associated with the provided code.

The successful response of the debit card creation call returns a 200 message that carries the unique identifier of the card that must be used in all card operation calls (see cardOperations). In addition to the cardId, the 200 response also provides a boolean indicating whether the card is operational or not, and a status field describing the card's status.

The possible statuses are detailed below:

PendingAck - For newly created physical cards that have not been activated. (see AckReception POST)

Temporarilyblocked - For self-manageable blocks. (see UnblockCard POST)

Cancel - For canceled cards (see CancelCard POST)

Active - For active cards

The sensitive card data (PAN and CVV) can be queried using the checkPan POST and checkCvv POST calls. However, it is important to note that such data must NOT be stored in databases as they imply cybersecurity requirements associated with the PCI standard that have been abstracted with the use of the cardId in the PayCaddy API.

The card's expiration date is presented in the successful response of the card creation call in the "dueDate" field following the format YYYYMM.

In case of any error or inconsistency with the provided data, the API will respond with a descriptive 400 error of one of the most common possible reasons:

  1. The userId to which the card is to be associated does not exist or is inactive.
  2. The walletId to which the card is to be associated does not exist or does not belong to the entered user.
  3. The code provided in the call does not match the type of user to which the card is to be associated.
  4. The code provided in the call does not match the type of card (virtual or physical) being attempted to create.

It is important to note that retries in case of errors must be managed responsibly, i.e., by creating time limits of at least 5 seconds before the retry and limiting the number of retries to 3.

CreditCard GET

Request URL: https://api.paycaddy.dev/v1/CreditCards/

The GET call for a Credit Card allows you to retrieve relevant information associated to a particular cardId provided through the following structure:

https://api.paycaddy.dev/v1/CreditCards/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
   "data": [
       {
           "id": "string",
           "userId": "string",
           "walletId": "string",
           "physicalCard": true,
           "code": "string"
           "isActive": true,
           "status": "string",
           "creationDate": "2022-08-01T21:57:16.932Z",
           "dueDate": 0
       }
   ]
}

This call is especially necessary in managing the transaction status of the card, since the successful response also includes the "isActive" boolean activity and the descriptive "status" field, in addition to the other fields in the successful response of card creation.In case an invalid cardId is sent, the PayCaddy API will respond with an HTTP 400 error.

If there is a HTTP 500 error encountered, report the incident to the PayCaddy support team.

Card Operations

AckReception POST

Request URL: https://api.paycaddy.dev/v1/cardOperations/ackReception

As a security measure in the logistical process of delivering physical plastics, by default, all physical cards created in the NeoBank API are born inactive. This is reflected in the "isActive" and "status" fields of successful responses for the creation of these cards, as well as when making a GET call for all types of cards, such as seen in the example below:

{
 "id": "string",
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string",
 "isActive": false,
 "status": "pendingAck",

 "creationDate": "2022-08-01T19:37:50.392Z",
 "dueDate": 0
}

Once a day, at a specific cut-off time, all physical cards created in the cycle are sent to the printing facility. The ackReception POST call will not return a successful response until the requested card has been printed, so it's a call that should only be made when the printed card is in hand or 48 hours after a successful response for card creation.

The purpose of this call is to allow the card to be delivered to the cardholder in an inactive state, waiting for validation of receipt from the cardholder once they have the card in hand.

The card-in-hand validation should be managed by comparing data entered by the cardholder (such as a range of the PAN or the CVV) with the results of calls made to obtain such sensitive data (see checkPan POST and checkCvv POST). If the entered data matches, the ackReception POST call can be made to activate the card for the first time, simply by sending the cardId of the card to be activated in the call.

The successful response to the call simply replicates the entered cardId. In case of encountering a 500 error, contact PayCaddy support team with the details of the case.

{
 "cardId": "string"
}

{
 "cardId": "string"
}

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

CheckPAN POST

Request URL: https://api.paycaddy.dev/v1/cardOperations/checkPan

This call allows access to sensitive data such as the card number and expiration date.
The responses to this call should not be stored in databases for security reasons.
It requires a cardId as an input and carries the following structure:

{
 "cardId": "string"
}

{
 "cardId": "string",
 "pan": "string",
 "expDate": 0
}

Unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 200 message.

In case of encountering an HTTP 500 error, contact the PayCaddy support team with the details of the case.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

CheckCVV POST

Request URL: https://api.paycaddy.dev/v1/cardOperations/checkCvv

This call allows access to sensitive data such as the card's CVV (Card Verification Value).
The responses to this call should not be stored in databases for security reasons.
It requires a cardId as an input and carries the following structure:

{
 "cardId": "string"
}

{
 "cardId": "string",
 "cvv": "string"
}

Unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 200 message.

In case of encountering an HTTP 500 error, contact the PayCaddy support team with the details of the case.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

BlockCard POST

Request URL: https://api.paycaddy.dev/v1/cardOperations/blockCard

This call allows for self-managed change of the card's activity status. This call directly affects the "isActive" boolean by transforming it to "false" based on a simple call that only carries the cardId.

{
 "cardId": "string"
}

{
 "cardId": "string",
 "isActive": "false"
}

The API could respond with a descriptive HTTP 400 error if it is an attempt to block a card that has already been previously blocked. For active cards, unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 200 message.

In case of encountering an HTTP 500 error, contact the PayCaddy support team with the details of the case.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

UnblockCard POST

Request URL: https://api.paycaddy.dev/v1/cardOperations/unblockCard

This call allows for self-managed change of the card's activity status. This call directly affects the "isActive" boolean by transforming it to "false" based on a simple call that only carries the cardId.

{
 "cardId": "string"
}

{
 "cardId": "string",
 "isActive": "true"
}

The API could respond with a descriptive HTTP 400 error if it is an attempt to unblock an active card. For previously blocked cards that are currently inactive, unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 200 message.

In case of encountering an HTTP 500 error, contact the PayCaddy support team with the details of the case.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

CheckPIN POST

Request URL: https://api.paycaddy.dev/v1/cardOperations/checkPin

This call allows access to the sensitive PIN data of the card, required for all ATM withdrawals and for some geographic regions' POS transactions.

Responses from this call should not be stored in databases for security reasons.

{
 "cardId": "string"
}

{
 "cardId": "string",
 "pin": "string"
}

Unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 200 message.

In case of encountering an HTTP 500 error, contact the PayCaddy support team with the details of the case.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

UnblockPIN POST

Request URL: https://api.paycaddy.dev/v1/cardOperations/unblockPin

This call allows the reactivation of a card's PIN after a security block occurs due to three incorrect attempts. The total number of acceptable incorrect attempts before the security block is a parameter that can be discussed during the project's scope definition phase, specifically for customized card profiles.

Responses from this call should not be stored in databases for security reasons.

{
 "cardId": "string"
}

{
 "cardId": "string",
 "pin": "string"
}

Unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 200 message.

In case of encountering an HTTP 500 error, contact the PayCaddy support team with the details of the case.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

ChangePIN POST

Request URL: https://api.paycaddy.dev/v1/cardOperations/changePin

This call allows managing the sensitive PIN data of the card, which is required for all ATM withdrawals and for some geographic areas in point-of-sale devices. The call is designed to assign a 4-digit PIN specified by the user. The responses to this call should not be stored in databases for security reasons.

Responses from this call should not be stored in databases for security reasons.

{
 "cardId": "string",
 "pin": "string"
}

{
 "cardId": "string",
 "pin": "string"
}

The API will respond with a descriptive HTTP 400 error if a PIN is sent that does not follow the 4 numeric digits format, otherwise, unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 200 message.

In case of encountering an HTTP 500 error, contact the PayCaddy support team with the details of the case.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

CancelCard POST

Request URL: https://api.paycaddy.dev/v1/cardOperations/cancelCard

This call allows for permanently canceling a previously created card. This call directly affects the "isActive" boolean, changing it to "false", as well as the "status" field changing it to "Cancel" from a call that simply loads the cardId.

{
 "cardId": "string"
}

{
 "cardId": "string",
 "isActive": "false"
}

The PayCaddy API could respond with a descriptive HTTP 400 error if it is an attempt to cancel a card that has already been canceled.

In case of encountering an HTTP 500 error, contact the PayCaddy support team with the details of the case.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

Webhooks

NotificationEnlist POST

Request URL: https://api.paycaddy.dev/v1/NotificationEnlist

The transactions generated on the Mastercard network by cards created in the NeoBank API are detailed in notifications via webhook that must be stored in a database to be consumed in a transaction management module.

These notifications are sent to a dedicated URL shared with the PayCaddy team securely by consuming the NotificationsEnlist POST endpoint. The structure of the call employed to enlist a URL to receive Transaction Notifications is detailed below:

{
 "URL": "string",
 "Password": "string"
}

The purpose of this call is specifically for assigning a webhook receiving URL and a security password that ensures the notifications received at the assigned address are legitimate and genuine.

During integration, once the NotificationEnlist POST call is successfully made, a test should be managed with the PayCaddy integration team to verify the successful reception of transaction payloads.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

Transaction Notifications

Each time a card issued in the NeoBank API makes a transaction on the Mastercard network, a payload like one of the four types of transactions exemplified below will be sent to the enlisted URL.

{
 "password": "password",
 "c1Tipo": "PeticionAutorizacion",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
"BDateUtcCreate": " YYYYMMDDHHMMSS ",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

{
 "password": "password",
 "c1Tipo": "ComunicacionAutorizacion",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
"BDateUtcCreate": " YYYYMMDDHHMMSS ",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

{
 "password": "password",
 "c1Tipo": "ComunicacionAnulacion",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
"BDateUtcCreate": " YYYYMMDDHHMMSS ",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

{
 "password": "password",
 "c1Tipo": "PeticionDevolucion",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
"BDateUtcCreate": " YYYYMMDDHHMMSS ",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

Main Types of Transactions

There are three main types of transactions that you will receive as online type:

  1. AuthorizationRequest: This transaction will decrease the customer's balance.
  2. AuthorizationCommunication: This transaction will also decrease the customer's balance.
  3. CancellationCommunication: This transaction will increase the available funds in the customer's wallet.
  4. ReversalRequest: This transaction type declares a request for a money reversal that will be processed offline through the Batch Process. This transaction will have a declared amount of "0". Once the network confirms the refund, the processed amount will be declared in the related "TransaccionCorregidaPositiva" through the Batch Process.

The transaction type is indicated in the "c1Tipo" field of the webhook. For example, if the "c1Tipo" field indicates that it is a "AuthorizationRequest" type transaction, it should be presented as a deduction in the available balance.

It's important to note that Transaction Notification webhooks are sent with attributes and values named in Spanish.
This documentation translates some terms for easy comprehension.
The field "c7FechaHoraTransaccion" represents the transaction time information in the timezone where the transaction was acquired in the format "YYYYMMDDhhmmss"
The field "BDateUtcCreate" represents the transaction time information in UTC timezone following the same format as the c7FechaHoraTransaccion

Additional Types of Transaction Notification

There are 9 additional types of transactions that you will receive online through the enlisted URL. It should be noted that these types do not affect balance and are merely informative of the card usage and describe the cause for rejected transactions.

These types will be seen as values in the "c1Tipo" field of the webhook notification:

  1. DENEGADA: The transaction was declined for an unspecified reason.
  2. DENEGADA. PIN INCORRECTO: The transaction was declined because the entered PIN is incorrect.
  3. DENEGADA. INTENTOS PIN EXCEDID: The transaction was declined because the maximum number of PIN entry attempts has been exceeded.
  4. DENEGADA. TARJETA NO EFECTIVA: The transaction was declined because the card is not valid or not active.
  5. DENEGADA. INCORRECTO CVV2: The transaction was declined because an incorrect CVV2 was entered.
  6. IMPORTE SUPERA LIMITE: The transaction was declined because the transaction amount exceeds the allowed limit for the card.
  7. NO HAY FONDOS: The transaction was declined because the account associated with the card does not have sufficient funds.
  8. EXCEDIDO NUMERO DE OPERACION DIARIO: The transaction was declined because the maximum number of daily operations allowed for the card has been exceeded.
  9. FECHA CADUCIDAD ERRONEO: The transaction was declined because an incorrect expiration date was entered.
  10. NotificacionDenegacion: These won't typically be seen in received webhooks but instead will be found when using the TransactionDetailList endpoint. They represent a transaction that has been declined due to insufficient funds.

In the schema of the JSON sent in these most of these additional types of notifications, the fields "c38NumeroAutorizacion" and "c11NumeroIdentificativoTransaccion" are present for customer convenience, however, it is important to mention that these fields will not always contain information and, therefore, will be presented as empty strings ("").

{
 "password": password,
 "c1Tipo": "DENEGADA. INCORRECTO CVV2",
 "c2CardId": cardId,
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
 "c11NumeroIdentificativoTransaccion": "",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

MoneySend Transactions

To stay informed about the specifics of an initiated MoneySend transaction, PayCaddy provides webhook notifications. These webhooks follow the same structure and travel through the same URL as other transaction notifications. However, MoneySend transactions can be identified by the c3CodigoProceso value of "820000".

{
"password": "password",
"c1Tipo": "PeticionAutorizacion",
"c2CardId": "cardId",
"c3CodigoProceso": "820000",
"c4ImporteTransaccion": "000000001617",
"c7FechaHoraTransaccion": "20220429052901",
"c11NumeroIdentificativoTransaccion": "000004339",
"c18CodigoActividadEstablecimiento": "5999",
"c19CodigoPaisAdquirente": "442",
"c38NumeroAutorizacion": "040031",
"c41TerminalId": "00227759",
"c42Comercio": "227759000156182",
"c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

When handling MoneySend webhook notifications, store them like any other transaction notification. The main difference is in how you process the transaction.

MoneySend transactions with c1Tipo equals to “PeticionAutorizacion” must be handled as positive transactions by adding funds to the recipient's wallet balance instead of deducting funds.
MoneySend transactions with c1Tipo equals to “ComunicacionAnulacion” must be handled as negative transactions by subtracting funds from the recipient's wallet balance instead of deducting funds.

When enlisting card or wallet transactions on the front-end, this should be reflected by showcasing the amount of said transactions as inputs to the wallets funds instead of charges.

Batch Process

Notice of Update: As of April 11, the functionality of our Batch Process has been expanded to include the "TransaccionConfirmada" webhook notification. This addition ensures comprehensive oversight over all transaction settlements, whether they match the initially authorized amounts or require adjustments.

In order to handle the completion of a transaction's lifecycle, we utilize a Batch Process to update and finalizes the lifecycle of each approved transaction, enabling fast visibility over actual settlement data in you card issuing program.

PayCaddy leverages this batch processing to deliver notifications through the conventional transactional webhook route (see NotificationEnlist POST) as part of a daily process to confirm and-or adjust the amount previously approved for each transaction.

Our system utilizes three key types of webhook notifications to manage various transaction outcomes:

  1. TransaccionCorregidaPositiva
    • Issued when the final settlement results in a positive adjustment to the initially authorized amount, thereby adding funds to the user’s wallet.
  2. TransaccionCorregidaNegativa
    • Issued when the final settlement results in a negative adjustment, thereby deducting funds from the user's wallet.
  3. TransaccionConfirmada (New)
    • Introduced to confirm that the transaction has settled exactly at the amount authorized initially, providing clear and precise confirmation of the transaction outcome.

A couple of examples of transactions that could be corrected through a batch process are:

  1. Car rental: When a customer rents a car, the rental company usually authorizes an initial amount on the customer's card to cover the cost of the rental and any possible damage. However, the final amount could vary depending on the actual use of the vehicle and other factors, such as the distance traveled or the cost of fuel. In these cases, the corrective message "TransaccionCorregidaPositiva" or "TransaccionCorregidaNegativa" could be used to adjust the final amount charged to the customer's card, once the vehicle has been returned and the final calculation has been made.
  2. Hotel bookings: When a customer reserves a hotel room, the hotel usually blocks an amount on the customer's card to cover the cost of the stay and possible additional charges, such as the minibar or room service. At the end of the stay, the final amount may be different from the initially blocked amount, depending on the actual use of these additional services. In these cases, the corrective message "TransaccionCorregidaPositiva" or "TransaccionCorregidaNegativa" could be used to adjust the final amount charged to the customer's card, once the final charges have been calculated.

Batch processing streamlines the handling of deferred transactions and ensures proper settlement, reducing discrepancies and the need for manual reconciliation. These webhooks improve transaction handling, minimize errors, and optimize overall management.

The majority of webhooks related to these corrective transactions will be sent during the same period overnight.
This is because our webhook generation process is a batch process that runs overnight to consolidate and notify if there were changes to the day's transactions.

Whenever possible, it is recommended to match the corrected transaction with the original transaction. This way, cardholders will have a better understanding of how and why their balance has been modified.

This practice improves transparency and fosters customer trust by allowing them to be aware of all transactions and changes made to their accounts. It is essential that cardholders feel informed and in control of their financial activity.

{
 "password": "password",
 "c1Tipo": "TransaccionCorregidaPositiva",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

{
 "password": "password",
 "c1Tipo": "TransaccionCorregidaNegativa",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

{
 "password": "password",
 "c1Tipo": "TransaccionConfirmada",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

Transaction Matching and Reporting

- Matching Transactions:

Each transaction includes a unique identifier (c11NumeroIdentificativoTransaccion), which is crucial for matching the corrected or confirmed settlement with its initial authorization. This matching process is essential for maintaining transaction integrity and provides cardholders with a clear understanding of how and why their balances were adjusted.

- Notification Details:
Webhook notifications furnish detailed information about the transaction, including the transaction amount, the identifier, and the type of adjustment or confirmation. This ensures all parties are accurately informed of the transaction status.
do this with the information that travels through the "c11NumeroIdentificativoTransaccion" field.

Once a transaction has been modified, it will not be modified again.

Although it is less common, it can also occur that a charge arrives only in the batch process and not online. If this is the case, the webhook may arrive with less information as presented below. It should be noted that this information is according to the network's protocol for handles these confirmations and does not depend on PayCaddy.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

Integrated KYC Notifications

As part of our Integrated KYC flow for Natural Persons, after users complete the identity verification steps at the URL shared in the kycURL field (see EndUser POST), our identity verification provider's system processes the submitted data and compares it with blacklists and does AML checks. Our API leverages these verifications and provides status notifications via webhook.

To properly receive notifications of KYC verifications, it is necessary to maintain an URL for receiving messages from the PayCaddy API via webhook. You must contact the PayCaddy integration team to configure the sending of notifications to that URL.

KYC Verification Webhooks

The KYC (Know Your Customer) Validation webhook is a notification sent to customers with relevant information about the status of the KYC verification process. The information is delivered in JSON format and may include different states and descriptions, depending on the verification cases.

Fields:

  • metadata: crucial information to identify the user in the form of their userId.
  • status: the status of the KYC verification, which can be "verified", "rejected" or "reviewNeeded".
  • description: a detailed description of the verification status.
  • fullName: the user's full name.
  • age: the user's age.
  • timeStamp: the ISO 8601 timestamp of the webhook response.

{
 "metadata": {
   "userId": "string"
 },
 "status": "string",
 "description": "string",
 "fullName": "string",
 "age": "string",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

Verification States and Descriptions

The webhook flow for a validation follows the diagram described below.

Integrated KYC validation flow and webhooks notifications.

Following this process flow, below are the webhooks corresponding to each state.
Each of these webhooks provide a description of the corresponding state, including rejection reasons in case of failed verifications. The corresponding descriptions are detailed below for your reference.

Verification Inputs Completed: This state indicates that a user has successfully completed KYC data capture through the kycURL and will have the structure and information shown below:

{
"metadata": {
"userId": "unique user identifier"
},
"status": "verification_inputs_completed",
"description": "Ongoing verification",
"fullName": "Document OCR capture ongoing",
"age": "Document OCR capture ongoing",
"timeStamp": "2023-03-16T09:42:18.8338086Z"
}

Verified: This state refers to when a user has successfully passed the KYC verification process. This indicates that the user has been successfully activated in our database and can proceed with other card creation and operations flows. The webhook response will have the following structure and information:

{
 "metadata": {
   "userId": "ID único del usuario"
 },
 "status": "verified",
 "description": "Verification signed",
 "fullName": "User's full name",
 "age": "User's age",
 "timeStamp": "ISO 8601 format timestamp"
}

Rejected: This state refers to when a user has not passed the KYC verification process. The different rejection cases are detailed below.

{
 "metadata": {
   "userId": "string"
 },
 "status": "rejected",
 "description": "Document doesn’t match input data",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "rejected",
 "description": "AML checks rejected",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "rejected",
 "description": "The user is underage",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "rejected",
 "description": "The document uploaded is expired",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "rejected",
 "description": "The document uploaded has issues",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "rejected",
 "description": "Validation Failed. User cannot be verified",
 "fullName": "User's complete name",
 "age": "null",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

ReviewNeeded: This state refers to when a user has not passed the KYC verification process. The different rejection cases are detailed below.

{
 "metadata": {
   "userId": "string"
 },
"status": "reviewNeeded",
 "description": "The document uploaded has issues",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
"status": "reviewNeeded",
 "description": "AML checks need to be reviewed",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "reviewNeeded",
 "description": "Government validation system inoperative",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "reviewNeeded",
 "description": "Validation failed. Pending compliance review",
 "fullName": "User's complete name",
 "age": "null",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

Discover how we simplify fintech for LatAm

Contact us