API explorerChangelog
Introduction

Sections

API explorer
Changelog

Theme switcher

Card transaction approval

The request webhook is triggered when a real-time authorization is requested. And should be answered with the correct code less than 1 second (1000 ms) to be processed, if not the operation will be declined and customer purchase reject.

For enhanced security, certain online transactions may require 3D Secure (3DS) authentication. When triggered, a verification code is sent either via SMS (default) or through a configured webhook. Learn more about webhook challenges in our 3DS documentation.

The request is composed by the following fields:

PRODUCT: CARDS

EVENT TYPE: AUTHORIZATION

STATUS: PENDING

Data Payload:

Field

Type

Description

card_id

String

Unique identifier of the card that needs the approval

bill_amount

Decimal with 2 digit precision

Amount of the operation will be billed on the system. Since all our cards are issued on USD, all transactions on the field will be on US Dollar

bill_currency_number

Number

Currency expressed on ISO 4217 format

bill_currency_code

String

Currency short name

transaction_amount

Decimal with 2 digit precision

Amount of the operation that client is going to spend. This is the same value as show on the checkout/POS

transaction_currency_number

Number

Currency expressed on ISO 4217 format

transaction_currency_code

String

Currency short name

exchange_rate

Number

If applied, the conversion rate applied to the amout. If not null will be sent.

fees

Object

Information about the fees that are involved in the transaction

merchant_data

Object

Information about the merchant that is involved in the transaction

Fees payload:

Field

Type

Description

atm_fees

Decimal with 2 digit precision

ATM fee charged to the transaction, if apply. Zero if no cost is incurred

fx_fees

Decimal with 2 digit precision

Currency conversion fee charged to the transaction, if apply. Zero if no cost is incurred

Merchant payload:

Field

Type

Description

id

String

Unique identifier of the merchant

name

String

Registered of the merchant

city

String

City where the merchant is registered, could be null

post_code

String

Postal code where the merchant is registered, could be null

state

String

State where the merchant is registered, could be null

country

String

Country where the merchant is registered. The country name is represented in 3 letter format ISO 3166-1 alpha-3.

mcc_category

String

Category name that the merchant has be registered

mcc_code

String

Numeric code of the category that merchant has be registered

Full payload example:

Plain text
{
  "product": "CARDS",
  "event_type": "APPROVAL",
  "operation_id": "ca0c57d2-b1c9-4bcd-9d5d-8d361cad6fddds1c",
  "status": "PENDING",
  "data": {
    "card_id": "ivZPARvNBLOSZx69q4DCBBGUfVhCMsLw",
    "amount": 100.2,
    "currency_number": 840,
    "currency_code": "USD",
    "exchange_rate": null,
    "channel": "ECOMMERCE",
    "created_at": "2024-05-15T21:38:57.677Z",
    "fees": {
      "atm_fees": 0,
      "fx_fees": 0
    },
    "merchant_data": {
      "id": "311178830000",
      "name": "Amazon Es",
      "city": "Barcelona",
      "post_code": "16633",
      "state": "Cataluña",
      "country": "ESP",
      "mcc_category": "Electronics Stores",
      "mcc_code": "5732"
    }
  }
}

Response:

In order to approve the transaction a OK (HTTP 200) response is needed in less that 1 second (1000 ms) time and you must respond with a authorization response to know to approve or decline the transaction

Field

Type

Description

response_code

String

Code that represent the result of the transaction.To approve a transaction, you can respond with 00. Otherwise, you may use any of the decline codes to decline the authorization.

Response codes:

Code

Name

Description

00

Approved

Transaction approved and can be processed.

51

Insufficient funds

Respond with this code when the card has insufficient funds to cover the authorized amount.

57

Cardholder problem

Transaction is not permitted to the cardholder

61

ATM daily amount exceeded

The ATM withdrawal amount limit has been exceeded

62

ATM country not allowed

ATM withdrawal is not permitted in the merchant's country.

77

Merchant exclusion

The issuer does not participate in that merchant category.

05

Rejected by other reason

Transaction reject by any other reason that is not included on the others options

Payload example:

Plain text
{
  "response_code": "00"
}
Was this section helpful?

What made this section unhelpful for you?

On this page
  • Card transaction approval