Webhooks

This service will be in charge of notifying you of events related to credit cards.

Digital signature request verification process

We send a set of HTTP headers to authenticate it along with the notification.

The HTTP headers we send are:

  • x-api-key : this header allows you to identify which api-secret you have to use in the event that multiple api-key and api-secret pairs have been configured.

  • x-signature : This header contains the digital signature (body + timestamp + endpoint) that must be verified to ensure request integrity. If the signature does not match, reject the order.

  • x-timestamp : this header contains the moment the order was signed in unix-epoch format so that you can verify that the signature has not expired.

  • x-endpoint : the endpoint to which the request is made and used to generate the signature. Use this header to regenerate the signature to be validated, compare it with the endpoint of your service and verify that they match.

The digital signature is an HMAC-SHA256 code constructed using the 'api-secret' and a series of bytes, composed of a timestamp concatenation, endpoint and request body coded in UTF-8.

The following is a pseudo-code to verify that the digital signature of a request is legitimate:

requestSignature = request.headers['x-signature']
signatureData = encode(request.headers['x-timestamp'] + request.headers['x-endpoint'] + request.body , 'UTF-8')
recreatedSignature = hmac(apiSecret, signatureData, 'SHA256')
validSignature = requestSignature == recreatedSignature

Notifications of processed transactions

You must inform us of this endpoint to receive notifications of processed transactions. You must return a type 2xx HTTP code so that the notification is not sent again. Otherwise, we will send it again.
Available parameters
Header Parameters
X-Api-Keystringrequired
This header helps you identify which api-secret to use if multiple api-key and api-secret pairs were configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (body + timestamp + endpoint) that must be verified to ensure request integrity. If the signature does not match, reject the order.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
This header has the moment the order was signed in unix-epoch format so that you can verify the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint where the order is placed and used to create the signature. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm that they match.
Example: X-Endpoint: /client/api/session/completed
Body Parameters
event_idstringrequired
Event identifier.
Example: transaction_processed
idempotency_keystringrequired
Idempotent identifier for creating the event.
Example: ctx-27KxRhP9YB4ouoyt6a5vVJlY9fR
dataobject
Information on the processed transaction

Was this section helpful to you?

POST/transactions
{
"event_id":
"transaction_processed"
"idempotency_key":
"ctx-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"data":{
"id":
"ctx-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"status":
"APPROVED"
"status_detail":
"APPROVED"
"credit_line_id":
"lcr-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"card_id":
"crd-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"card_last_four":
"5439"
"user_id":
"usr-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"merchant_id":
"BGQ"
"merchant_name":
"Lending Store"
"installments_quantity":
"5"
"transaction_date_time":
"2023-05-16T14:00:00"
"local_amount":{
...
}
}
}
Response examples

Reversed transaction notifications

You must inform us of this endpoint to receive notifications of processed transactions. You must return a type 2xx HTTP code so that the notification is not sent again. Otherwise, we will send it again.
Available parameters
Header Parameters
X-Api-Keystringrequired
This header helps you identify which api-secret to use if multiple api-key and api-secret pairs were configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (body + timestamp + endpoint) that must be verified to ensure request integrity. If the signature does not match, reject the order.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
This header has the moment the order was signed in unix-epoch format so that you can verify the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint where the order is placed and used to create the signature. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm that they match.
Example: X-Endpoint: /client/api/session/completed
Body Parameters
event_idstringrequired
Event identifier.
Example: operation_reverted
idempotency_keystringrequired
Idempotent identifier for creating the event.
Example: ctx-27KxRhP9YB4ouoyt6a5vVJlY9fR
dataobject
Reverse transaction information

Was this section helpful to you?

POST/reverted-operations
{
"event_id":
"operation_reverted"
"idempotency_key":
"ctx-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"data":{
"id":
"ctx-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"status":
"REVERTED"
"credit_line_id":
"lcr-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"card_id":
"crd-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"card_last_four":
"5439"
"user_id":
"usr-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"merchant_id":
"BGQ"
"merchant_name":
"Lending Store"
"installments_quantity":
"5"
"reverted_date_time":
"2023-05-16T14:00:00"
"local_amount":{
...
}
}
}
Response examples

Credit line status change notifications

Please provide us with this endpoint to receive notifications for credit line status changes. You'll need to return an HTTP status code in the 2xx range to prevent us from resending the notification. Otherwise, we will resend it.
Available parameters
Header Parameters
X-Api-Keystringrequired
This header helps you identify which api-secret to use if multiple api-key and api-secret pairs were configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (body + timestamp + endpoint) that must be verified to ensure request integrity. If the signature does not match, reject the order.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
This header has the moment the order was signed in unix-epoch format so that you can verify the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint where the order is placed and used to create the signature. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm that they match.
Example: X-Endpoint: /client/api/session/completed
Body Parameters
event_idstringrequired
Event identifier.
Example: credit_line_paused
Enum: credit_line_pausedcredit_line_unpausedcredit_line_canceled
idempotency_keystringrequired
Idempotent identifier for creating the event.
Example: 27KxRhP9YB4ouoyt6a5vVJlY9fR
dataobject
Information on the affected line of credit

Was this section helpful to you?

POST/credit-lines
{
"event_id":
"credit_line_paused"
"idempotency_key":
"27KxRhP9YB4ouoyt6a5vVJlY9fR"
"data":{
"credit_line_id":
"lcr-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"status":
"PAUSED"
"reason":
"IN_ARREARS"
}
}
Response examples

Notifications of User Entry, Exit, or Continued Delinquency

You will need to provide us with this endpoint to receive notifications of a user's entry, exit, or continued delinquency. We expect a 2XX response to ensure you received the notification. Otherwise, we will resend it.

Available parameters
Header Parameters
X-Api-Keystringrequired
This header helps you identify which api-secret to use if multiple api-key and api-secret pairs were configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (body + timestamp + endpoint) that must be verified to ensure request integrity. If the signature does not match, reject the order.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
This header has the moment the order was signed in unix-epoch format so that you can verify the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint where the order is placed and used to create the signature. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm that they match.
Example: X-Endpoint: /client/api/session/completed
Body Parameters
event_idstringrequired
Event identifier.
Example: user_in_arrears
Enum: user_in_arrearsuser_out_of_arrearsuser_remains_in_arrears
idempotency_keystringrequired
Idempotent identifier for creating the event.
Example: 27KxRhP9YB4ouoyt6a5vVJlY9fR
dataobject
Information on the affected user

Was this section helpful to you?

POST/debt
{
"event_id":
"user_in_arrears"
"idempotency_key":
"27KxRhP9YB4ouoyt6a5vVJlY9fR"
"data":{
"user_id":
"usr-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"credit_line_id":
"lcr-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"effective_at":
"2022-12-15T13:55:00"
}
}
Response examples

Notifications of created summaries

You will have to indicate this endpoint to receive the notifications of created summaries. You must return a type 2xx HTTP code so that the notification is not sent again Otherwise, we will send it again.
Available parameters
Header Parameters
X-Api-Keystringrequired
This header helps you identify which api-secret to use if multiple api-key and api-secret pairs were configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (body + timestamp + endpoint) that must be verified to ensure request integrity. If the signature does not match, reject the order.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
This header has the moment the order was signed in unix-epoch format so that you can verify the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint where the order is placed and used to create the signature. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm that they match.
Example: X-Endpoint: /client/api/session/completed
Body Parameters
event_idstringrequired
Event identifier.
Example: statement_created
Enum: statement_created
idempotency_keystringrequired
Idempotent identifier for creating the event.
Example: lst-27KxRhP9YB4ouoyt6a5vVJlY9fR
dataobject
Information on the created summary

Was this section helpful to you?

POST/statements
{
"event_id":
"statement_created"
"idempotency_key":
"lst-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"data":{
"id":
"lst-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"credit_line_id":
"lcr-27KxRhP9YB4ouoyt6a5vVJlY9fR"
}
}
Response examples