PayCaddy API Documentation

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.

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.

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.

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

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.

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').

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.

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

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.

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.

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.

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

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

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

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

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

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.

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.

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.

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.

‍

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 ("").

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

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.

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.

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.

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.

Verification States and Descriptions

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

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

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