Card Transactions

Credit card transactions are always initiated through the API. Only local currencies (BRL, MXN, COP and CLP) are supported.

Card Tokenization

You can register a credit card for a specific customer, so you don't need to register the same card every transaction. Customers can have their cards registered to make transactions.

NOTE: If you use version 2 on our client js, you need send us the threeds object

curl -X POST "https://api.facilitapay.com/api/v1/subject/:subject_id/credit_cards" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "credit_card": {
    "card_number": "2584958561024786",
    "card_expiration_date": "12/2030",
    "card_brand": "Visa",
    "card_security_code": "333",
    "fullname": "Credit Card Holder Name",
    "threeds": {
      "softDescriptor": "Attrus",
      "httpAcceptBrowserValue": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
      "userAgentBrowserValue": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
      "httpBrowserJavaEnabled": "false",
      "httpBrowserLanguage": "en-US",
      "httpBrowserColorDepth": "24",
      "httpBrowserScreenHeight": "570",
      "httpBrowserScreenWidth": "1080",
      "httpBrowserJavaScriptEnabled": "true",
      "httpBrowserTimeDifference": "180",
      "ipAddress": "187.18.136.135",
      "challengeWindowSize": "250x400",
      "df_reference_id": "0_2ecc0eb3-b5f3-46a7-9dd2-481dda92290b",
      "mcc": "8999"
    }
  }
}'

HTTP Request

POST /subject/:subject_id/credit_cards

Path Parameters

Parameter	Description	Type	Required
`subject_id`	Person or Company's ID	string	true

Body Parameters

Parameter	Description	Type	Required
`credit_card`	An object containing all the required values	object	true
`card_number`	The card number without spaces	string	true
`card_expiration_date`	Card expiration date in `MM/YY` format	string	true
`card_brand`	Card brand, such as Visa, Mastercard, Amex or Elo	string	true
`card_security_code`	Partner's customer/company UUID	string	true
`fullname`	Cardholder's name as it appears on the card	string	true
`threeds`	Data containing at least the following required values:	object	true
`threeds.softDescriptor`	It is a short description of the merchant that will appear on the buyer's credit card statement. If this field was filled will be used, otherwise the social name of merchant will be used also append the `attrus`, e.g.: `MerchantName*attrus`. Any characters that exceed this limit will be truncated.	string	false
`threeds.httpAcceptBrowserValue`	Value of the Accept Header of the Customer's browser.	string	true
`threeds.httpBrowserLanguage`	Customer's browser language according to https://www.techonthenet.com/js/language_tags.php	string	true
`threeds.httpBrowserJavaEnabled`	If Java is enabled on customer browser. Options: `true`, `false`	string	true
`threeds.httpBrowserJavaScriptEnabled`	If JavaScript is enabled on customer browser. Options: `true`, `false`	string	true
`threeds.httpBrowserColorDepth`	Number of bits used to display images.	string	true
`threeds.httpBrowserScreenHeight`	Height of the Customer's screen resolution.	string	true
`threeds.httpBrowserScreenWidth`	Width of the Customer screen resolution.	string	true
`threeds.httpBrowserTimeDifference`	Difference in minutes between GMT time and that of the Customer's browser.	string	true
`threeds.userAgentBrowserValue`	The exact value of the User Agent Header.	string	true
`threeds.ipAddress`	It is the IP address of the Customer's device.	string	true
`threeds.challengeWindowSize`	The size of the challenge window displayed to the shopper. Options: `fullPage`, `250x400`, `390x400`, `500x600`, `600x400`.	string	true
`threeds.df_reference_id`	Session ID generated after the DDC is completed.	string	true
`threeds.mcc`	Dynamic MCC. If you have multiple merchant category codes, the MCC lets you send a different merchant category code per transaction. Options: `8999`, `5045`, `4722`, `8299`, `5947`, `5065`, `7372`	string	true

warning

Common mistakes

{
  "data": {
    "status": "tokenized",
    "inserted_at": "2021-06-25T19:44:40.397583",
    "id": "788094b0-76fc-428a-bd1a-52489cef0dbe"
  }
}

Solution: Provide a valid credit card verifying the card data and subject

Solution: Please provide the credit card holder's name as it appears on the card

Solution: Please provide a valid credit card number

Note: In the sandbox environment, all cards will be automatically registered as tokenized.

Confirm Card Tokenization

After tokenization card and if has challenge, you need confirm using this route.

curl -X POST "https://api.facilitapay.com/api/v1/subject/:subject_id/credit_cards/:credit_card_id/confirm" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "credit_card": {
    "card_number": "2584958561024786",
    "card_expiration_date": "12/2030",
    "card_brand": "Visa",
    "card_security_code": "333",
    "fullname": "Credit Card Holder Name"
  }
}'

HTTP Request

POST /subject/:subject_id/credit_cards/:credit_card_id/confirm

Path Parameters

Parameter	Description	Type	Required
`subject_id`	Person or Company's ID	string	true
`credit_card_id`	Credit card ID	string	true

Body Parameters

Parameter	Description	Type	Required
`credit_card`	An object containing all the required values	object	true
`card_number`	The card number without spaces	string	true
`card_expiration_date`	Card expiration date in `MM/YY` format	string	true
`card_brand`	Card brand, such as Visa, Mastercard, Amex or Elo	string	true
`card_security_code`	Partner's customer/company UUID	string	true
`fullname`	Cardholder's name as it appears on the card	string	true

warning

Common mistakes

{
  "data": {
    "status": "tokenized",
    "inserted_at": "2021-06-25T19:44:40.397583",
    "id": "788094b0-76fc-428a-bd1a-52489cef0dbe"
  }
}

Solution: Provide a valid credit card verifying the card data and subject

Solution: Please provide the credit card holder's name as it appears on the card

Example - Credit Card Transaction

This example covers a transaction of BRL 2500.50 using the credit card for an Attrus account to be converted to USD and sent to the partner's USD bank account. Note that it provides the credit card details on the fly. If you want to register(tokenize) the credit card prior to the transaction, please refer to the credit card registration endpoint above.

curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "transaction": {
    "currency": "BRL",
    "exchange_currency": "USD",
    "value": "2500.50",
    "from_credit_card": {
      "card_number": "4761739001010036",
      "card_expiration_date": "12/2022",
      "card_security_code": "123",
      "card_brand": "Visa",
      "fullname": "Jose Silva"
    },
    "to_bank_account_id": "766eadfc-f020-4d2a-bed3-c9a95623ed24",
    "subject_id": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21"
  }
}'

200OK

{
  "data": {
    "value": "2500.50",
    "to_bank_account": {
      "routing_number": "29483242",
      "owner_name": null,
      "owner_document_number": null,
      "owner_company": {
        "social_name": "Dagny Taggart",
        "id": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21",
        "document_type": "passport",
        "document_number": "J83579487346"
      },
      "intermediary_bank_account": null,
      "id": "766eadfc-f020-4d2a-bed3-c9a95623ed24",
      "iban": null,
      "currency": "USD",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": "BDK9348309",
        "name": "Bank D'Anconia",
        "id": "77c1ef53-9376-4a96-9aa2-af038a3ba39d",
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": "0101100",
      "aba": null
    },
    "subject_is_receiver": true,
    "subject_id": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21",
    "subject": {
      "updated_at": "2021-04-29T22:15:10.988964",
      "status": "approved",
      "social_name": "Dagny Taggart",
      "required_clearance_level": 1,
      "references": [],
      "phone_number": null,
      "net_monthly_average_income": "15000.00",
      "inserted_at": "2021-03-08T19:56:22.628081",
      "id": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21",
      "fiscal_country": "Brasil",
      "email": null,
      "document_type": "passport",
      "document_number": "J83579487346",
      "clearance_level": 1,
      "birth_date": "1965-04-06",
      "address_street": "Sherman Ave",
      "address_state": "DC",
      "address_postal_code": "12394",
      "address_number": "2252",
      "address_country": "United States (US)",
      "address_complement": "Apt 101",
      "address_city": "Washington"
    },
    "status": "identified",
    "source_name": "Dagny Taggart",
    "source_document_type": "passport",
    "source_document_number": "J83579487346",
    "inserted_at": "2021-05-07T18:22:11.346220",
    "id": "8da57ca6-2f09-460c-b155-8358ed7657c9",
    "from_credit_card": {
      "status": "tokenized",
      "phone_number": "99123-2313",
      "phone_country_code": "55",
      "phone_area_code": "18",
      "inserted_at": "2021-05-07T18:22:11.345036",
      "id": "e5e6e87d-77e0-45c0-9fed-e2e2f36dffca",
      "document_type": "CPF",
      "document_number": "24189952087",
      "birthdate": "1990-12-03"
    },
    "from_bank_account": null,
    "for_exchange": true,
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "currency": "BRL",
    "cleared": true,
    "bank_transaction": null
  }
}

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required	Required For
`transaction`	An object containing all the required values	object	true
`currency`	Source currency for the transaction (ISO 4217 format)	string	true
`exchange_currency`	Currency to be exchanged (ISO 4217 format)	string	true
`value`	Value to be exchanged (in the source currency)	string	true
`from_credit_card_id`	A registered (tokenized) credit card ID can also be provided instead of the whole credit card data	string	false	When you don't send from_credit_card
`from_credit_card`	An object, containing the following parameters:	object	false	When you don't send from_credit_card_id
`from_credit_card.card_number`	Credit card number. Valid credit card numbers would also work, but debit card numbers won't	string	false
`from_credit_card.card_expiration_date`	Card expiration date (mm/yyyy)	string	false
`from_credit_card.card_security_code`	3-digit card security code	string	false
`from_credit_card.card_brand`	Brand of the credit card used in the transaction (e.g., Visa, MasterCard)	string	false
`from_credit_card.fullname`	Full name of the credit card's owner	string	false
`from_credit_card.birthdate`	Birthdate of the credit card owner	string	false
`from_credit_card.document_type`	Document type of the credit card owner	string	false
`from_credit_card.document_number`	Document number of the credit card owner	string	false
`from_credit_card.phone_country_code`	Country phones code (2 digits: BR +55; MX +52; COP +57; CL +52)	string	false
`from_credit_card.phone_area_code`	Internal country area code	string	false
`from_credit_card.phone_number`	Contact phone number linked to the credit card holder	string	false
`to_bank_account_id`	ID of an USD bank account from the partner	string	true
`subject_id`	ID of one of the partner's customer	string	true

Note: All successful exchange transactions initiated in sandbox will be stored as wired. In the production environment they will be initially on the identified status. In either environment, if no exchange is created the transaction will be stored as identified, if it is approved.

Credit card transactions in Brazil 🇧🇷

Supported brands: Amex, Diners, Discover, JCB, Maestro, Mastercard and Visa

Refer to the payloads and tables to the right and below for the required parameters.

For sandbox, you can use a checkout page sample available on our portal or via the following link. This page will help you understand the needed information and the whole flow from the credit transactions.

We highly recommend testing the checkout page first before initiating direct API calls, because you can adapt it to your front-end environment.

Download sample page

curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "transaction": {
    "currency": "BRL",
    "exchange_currency": "BRL",
    "value": "125.00",
    "from_credit_card": {
      "card_type": "credit",
      "card_number": "4000000000001091",
      "card_expiration_date": "01/2034",
      "card_security_code": "395",
      "card_brand": "master",
      "fullname": "Jose Silva"
    },
    "threeds": {
      "softDescriptor": "Attrus",
      "httpAcceptBrowserValue": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
      "httpBrowserLanguage": "en-US",
      "httpBrowserJavaEnabled": "false",
      "httpBrowserJavaScriptEnabled": "true",
      "httpBrowserColorDepth": "24",
      "httpBrowserScreenHeight": "969",
      "httpBrowserScreenWidth": "1250",
      "httpBrowserTimeDifference": "240",
      "userAgentBrowserValue": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36",
      "ipAddress": "127.0.0.1",
      "challengeWindowSize": "250x400"
    },
    "to_bank_account_id": "3686155e-f5f6-4e5b-97e7-60473a506b8c",
    "subject_id": "6b724825-ce7e-4da2-9def-d75957fee745",
    "meta": {
      "version": 2,
      "df_reference_id": "0_165b7a2f-359a-4efb-aae2-6e09cb786cf9",
      "mcc": "8999"
    }
  }
}'

{
  "data": {
    "value": "125.00",
    "to_bank_account": {
      "routing_number": null,
      "owner_name": "Biriweb Serviços de Internet Ltd",
      "owner_document_number": "12345678901",
      "owner_company": {
        "social_name": "Biriweb Serviços de Internet Ltd",
        "id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2",
        "document_type": "cpf",
        "document_number": "12345678901"
      },
      "internal": true,
      "id": "3686155e-f5f6-4e5b-97e7-60473a506b8c",
      "currency": "BRL",
      "pix_info": null,
      "owner_document_type": null,
      "nickname": null,
      "intermediary_bank_account": null,
      "iban": null,
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": null,
        "name": "Internal",
        "ispb": null,
        "id": "6facab8d-573e-44d0-a4bd-ce2600368263",
        "country": "BRA",
        "code": "999"
      },
      "account_type": "conta-corrente",
      "account_number": null,
      "aba": null
    },
    "threeds_challenge": {
      "transaction_id": "bc897a32-f833-4208-811a-4cdb6119e168",
      "threeds_data": {
        "transaction_id_3ds": "daIar3L7pGeDGnvRr8b0",
        "three_ds_version": "2.1.0",
        "payload": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJhNGQ2M2RlNC05NTg0LTQxMWQtODYwZS1hYjljYjNlNTRmMTQiLCJhY3NUcmFuc0lEIjoiYjE2MjI3YjYtMWUzNy00ZmIzLWJmMzAtNWMwYzQzZjcxNjY0IiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAxIn0",
        "acs_url": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp"
      },
      "jwt_challenge": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJPYmplY3RpZnlQYXlsb2FkIjp0cnVlLCJPcmdVbml0SWQiOiI2N2ExMTcwNGVhMTI3MDVmNzk2YTlkM2YiLCJQYXlsb2FkIjp7IkFDU1VybCI6Imh0dHBzOi8vMG1lcmNoYW50YWNzc3RhZy5jYXJkaW5hbGNvbW1lcmNlLmNvbS9NZXJjaGFudEFDU1dlYi9jcmVxLmpzcCIsIlBheWxvYWQiOiJleUp0WlhOellXZGxWSGx3WlNJNklrTlNaWEVpTENKdFpYTnpZV2RsVm1WeWMybHZiaUk2SWpJdU1TNHdJaXdpZEdoeVpXVkVVMU5sY25abGNsUnlZVzV6U1VRaU9pSmhOR1EyTTJSbE5DMDVOVGcwTFRReE1XUXRPRFl3WlMxaFlqbGpZak5sTlRSbU1UUWlMQ0poWTNOVWNtRnVjMGxFSWpvaVlqRTJNakkzWWpZdE1XVXpOeTAwWm1JekxXSm1NekF0TldNd1l6UXpaamN4TmpZMElpd2lZMmhoYkd4bGJtZGxWMmx1Wkc5M1UybDZaU0k2SWpBeEluMCIsIlRyYW5zYWN0aW9uSWQiOiJkYUlhcjNMN3BHZURHbnZScjhiMCJ9LCJSZXR1cm5VcmwiOiJodHRwOi8vMC4wLjAuMDo0MDAwL2FwaS92MS90cmFuc2FjdGlvbnMvYmM4OTdhMzItZjgzMy00MjA4LTgxMWEtNGNkYjYxMTllMTY4LzNkc19jYWxsYmFjayIsImlhdCI6MTc1MzM4ODg1MCwiaXNzIjoiNjdhMTE3MDUyN2NkZDIwNDk2ZDlmODkxIiwianRpIjoiZmI2N2JhN2EtMTg2My00ZGE4LWI0ZjMtNDRjZTFhZGVmZmFkIn0.pVoCMPHFGCnLL31v0y7YmjTqwKe1eJYkUfG3Iu4kIEk"
    },
    "subject_is_receiver": false,
    "subject_id": "6b724825-ce7e-4da2-9def-d75957fee745",
    "subject": {
      "updated_at": "2025-07-24T20:27:29.887571",
      "status": "reproved",
      "social_name": "Company Social Name LTDA",
      "rfc_pf": null,
      "required_clearance_level": 2,
      "references": [],
      "phone_number": "9876543210",
      "phone_country_code": "BR",
      "phone_area_code": "11",
      "net_monthly_average_income": "5000.00",
      "inserted_at": "2021-05-12T23:19:38.477358",
      "id": "6b724825-ce7e-4da2-9def-d75957fee745",
      "fiscal_country": "BR",
      "email": "[email protected]",
      "document_type": "cpf",
      "document_number": "12345678909",
      "clearance_level": 1,
      "birth_date": "1985-08-31",
      "address_street": "Brazil test",
      "address_state": "SP",
      "address_postal_code": "1234567",
      "address_number": "123",
      "address_neighborhood": "Centro",
      "address_country": "BR",
      "address_complement": "Apt. 101",
      "address_city": "Sao Paulo"
    },
    "status": "pending",
    "source_name": "Company Social Name LTDA",
    "source_document_type": "cpf",
    "source_document_number": "12345678909",
    "payment_method": null,
    "meta": {
      "version": 2,
      "df_reference_id": "0_847562c4-87fb-4215-b4fb-90ca4d6aefdc",
      "mcc": "8999"
    },
    "inserted_at": "2025-07-24T20:27:29.867220",
    "id": "bc897a32-f833-4208-811a-4cdb6119e168",
    "from_credit_card": {
      "status": "not_tokenized",
      "inserted_at": "2025-07-24T20:27:29.866374",
      "id": "86e291b9-26bf-4252-a074-158ebe6464b6",
      "masked_card_number": "400000******1091"
    },
    "exchanged_value": "125.00",
    "from_bank_account": null,
    "for_exchange": false,
    "exchange_under_request": false,
    "exchange_currency": "BRL",
    "estimated_value_until_exchange": false,
    "currency": "BRL",
    "cleared": false,
    "bank_transaction": null
  }
}

To create using the API call you will use the following endpoint:

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required
`transaction`	transaction data containing at least the following required values:	object	true
`currency`	Origin currency	string	true
`exchange_currency`	Destination currency	string	true
`value`	Total amount to be charged. Only numbers with exponent size 2 are allowed. (e.g.: `12.34`).	string	true
`from_credit_card`	Data containing at least the following required values:	object	true
`from_credit_card.card_number`	The card number without spaces	string	true
`from_credit_card.card_expiration_date`	Card expiration date in MM/YYYY format	string	true
`from_credit_card.card_brand`	Card brand, such as `visa`, `mastercard`, or `elo`	string	true
`from_credit_card.card_security_code`	3-digit card security code	string	true
`from_credit_card.fullname`	Cardholder's full name	string	true
`threeds`	Data containing at least the following required values:	object	true
`threeds.softDescriptor`	It is a short description of the merchant that will appear on the buyer's credit card statement. The first 13 characters will be appended to the string `Attrus`, e.g.: `AttrusAirbnb`. Any characters that exceed this limit will be truncated.	string	false
`threeds.httpAcceptBrowserValue`	Value of the Accept Header of the Customer's browser.	string	true
`threeds.httpBrowserLanguage`	Customer's browser language according to https://www.techonthenet.com/js/language_tags.php	string	true
`threeds.httpBrowserJavaEnabled`	If Java is enabled on customer browser. Options: `true`, `false`	string	true
`threeds.httpBrowserJavaScriptEnabled`	If JavaScript is enabled on customer browser. Options: `true`, `false`	string	true
`threeds.httpBrowserColorDepth`	Number of bits used to display images.	string	true
`threeds.httpBrowserScreenHeight`	Height of the Customer's screen resolution.	string	true
`threeds.httpBrowserScreenWidth`	Width of the Customer screen resolution.	string	true
`threeds.httpBrowserTimeDifference`	Difference in minutes between GMT time and that of the Customer's browser.	string	true
`threeds.userAgentBrowserValue`	The exact value of the User Agent Header.	string	true
`threeds.ipAddress`	It is the IP address of the Customer's device.	string	true
`threeds.challengeWindowSize`	The size of the challenge window displayed to the shopper. Options: `fullPage`, `250x400`, `390x400`, `500x600`, `600x400`.	string	true
`to_bank_account_id`	Partner internal bank account ID	string	true
`subject_id`	The ID of the person or company involved in the transaction.	string	true
`meta`	Transaction metadata.	object	true
`meta.version`	Version of the API. Use the value 2.	number	true
`meta.df_reference_id`	Session ID generated after the DDC is completed.	string	true
`meta.mcc`	Dynamic MCC. If you have multiple merchant category codes, the MCC lets you send a different merchant category code per transaction. Options: `8999`, `5045`, `4722`, `8299`, `5947`, `5065`, `7372`	string	true

Test Cards

Card Number	Description
`4000000000001000`	Test Case 1: Successful Frictionless Authentication (Visa)
`5200000000001005`	Test Case 1: Successful Frictionless Authentication (Mastercard)
`4000000000001018`	Test Case 2: Failed Frictionless Authentication
`4000000000001026`	Test Case 3: Attempts Stand-In Frictionless Authentication
`4000000000001034`	Test Case 4: Unavailable Frictionless Authentication from the Issuer
`4000000000001042`	Test Case 5: Rejected Frictionless Authentication by the Issuer
`4000000000001059`	Test Case 6: Authentication Not Available on Lookup
`4000000000001067`	Test Case 7: Error on Lookup
`4000000000001075`	Test Case 8: Timeout on cmpi_lookup Transaction
`4000000000001091`	Test Case 10: Successful Step Up Authentication (Visa)
`5200000000001096`	Test Case 10: Successful Step Up Authentication (Mastercard)
`4000000000001109`	Test Case 11: Failed Step Up Authentication
`4000000000001117`	Test Case 12: Step Up Authentication is Unavailable
`4000000000001125`	Test Case 13: Error on Authentication

Important Notes

From August 2025, this will be the default endpoint to create transactions. Check out the older version on the Credit card transactions Brazil (Deprecated) section.
A transaction with the status of identified means that the payment was approved without challenge.
A transaction with the status of pending means that the payment is awaiting the challenge resolution. If the challenge was requested, but it is not completed within 5 minutes (i.e., timeout), the status is updated to canceled.
A transaction with the status of canceled means that the payment was canceled by some reason, see the canceled_reason field on API response for more details.

Troubleshooting

warning

Common errors for card transactions

This error occurs when:

Your partner account is configured to require 3DS authentication (only_3DS: true)

The transaction was submitted without the required 3DS data (missing threeds object or meta.df_reference_id)

Solution: Ensure you are using the 3DS flow as documented above. Include the threeds object with all required parameters and the meta object with version, df_reference_id, and mcc fields. If you are using the checkout page, make sure the DDC (Device Data Collection) step is completed before submitting the transaction.

Credit card transactions in Brazil 🇧🇷 - JWT for DDC

Generates a new JWT to be used in DDC (Device Data Collection) step. This token is required, otherwise, the DDC step will fail.

The DDC step is performed on the shopper's browser to collect device data as part of the authentication process. After the DDC step is done, it returns a SessionId, which will be sent as df_reference_id in the payment request.

For a practical example of how the DDC step is implemented, refer to the provided sample checkout page (in the previous section). This sample demonstrates the process of obtaining the JWT from the /acquirer_v2/ddc/token/ endpoint, passing it to the frontend (via facilitapay.setJwtForDdc(jwt)), and performing device data collection in the shopper's browser. Reviewing this HTML sample will help clarify how to integrate the DDC flow into your own checkout page.

curl -X GET "https://api.facilitapay.com/api/v1/acquirer_v2/ddc/token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."

200OK

{
  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

HTTP Request

GET /acquirer_v2/ddc/token

Credit card transactions in Mexico 🇲🇽

Supported brands: Mastercard and Visa

For testing, you can use a checkout page sample available on our portal or via the following link. This page will help you understand the needed information and the whole flow from the credit transactions.

We highly recommend testing the checkout page first before initiating direct API calls, because you can adapt it to your front-end environment. Sample checkout pages links: One-time purchase Tokenized purchase

The source code for the HTML file is available below.

To create using the API call you will use the following endpoint:

Download sample page

curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "transaction": {
    "currency": "MXN",
    "exchange_currency": "USD",
    "value": "2000.00",
    "from_credit_card": {
      "card_number": "4456524869770255",
      "card_expiration_date": "03/27",
      "card_security_code": "234",
      "card_brand": "Visa",
      "card_type": "Credit",
      "fullname": "Luiz Abreu Nieto"
    },
    "threeds": { "jwt": "eyJhbGciOiJIUzI1NiIsInR5cC..."
    },
    "to_bank_account_id": "{{partner_usd_account_id}}",
    "subject_id": "{{mx_person_id}}"
  }
}'

200OK

{
  "data": {
    "value": "2000.00",
    "to_bank_account": {
      "routing_number": "Further Credit To / REF: SWS2319371",
      "pix_info": null,
      "owner_name": "REARDEN STEEL CO. Ltd.",
      "owner_document_number": "2348909854385",
      "owner_company": {
        "social_name": "POWER HOME THEATER",
        "id": "f64e512c-1a81-42d9-9ac9-05f369bc98e3",
        "document_type": "tax_id",
        "document_number": "2348909854385"
      },
      "nickname": "Power Conta 1",
      "intermediary_bank_account": null,
      "id": "a1db04a1-ddc9-4aa8-a0a5-2c74cf9505d0",
      "iban": null,
      "currency": "USD",
      "branch_number": null,
      "branch_country": "USD",
      "bank": {
        "swift": "MT2502041",
        "name": "M&T Bank",
        "id": "d6f801e9-57c0-43af-8b11-07b8bd4fff0f",
        "country": null,
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": "00416612332",
      "aba": null
    },
    "threeds_data": {
      "three_ds_version": "1.0.2",
      "secure_id": "1bff5e25-6cac-4f59-8670-fbce6d00762b",
      "pareq": "sandbox",
      "authentication_transaction_id": "OWgXwASsYPW4hr1ATcf0",
      "acs_url": ""
    },
    "subject_is_receiver": false,
    "subject_id": "9e474282-8b37-4d05-9c77-eab27976cfe9",
    "subject": {
      "updated_at": "2024-02-05T18:48:35.654100",
      "status": "approved",
      "social_name": "HORACIO SOTO MORALES",
      "rfc_pf": null,
      "required_clearance_level": 2,
      "references": [],
      "phone_number": "434898404898",
      "net_monthly_average_income": "50000.00",
      "inserted_at": "2021-03-26T20:22:04.358980",
      "id": "9e474282-8b37-4d05-9c77-eab27976cfe9",
      "fiscal_country": "Mexico",
      "email": "[email protected]",
      "document_type": "curp",
      "document_number": "SOMH031031HSRTRRA3",
      "clearance_level": 2,
      "birth_date": null,
      "address_street": "Calle Cannobio",
      "address_state": "PS",
      "address_postal_code": "39847389",
      "address_number": "75",
      "address_neighborhood": "Aldea Alpina",
      "address_country": "Mexico",
      "address_complement": "",
      "address_city": "Nuova Lima"
    },
    "status": "pending",
    "source_name": "HORACIO SOTO MORALES",
    "source_document_type": "curp",
    "source_document_number": "SOMH031031HSRTRRA3",
    "payment_method": null,
    "meta": null,
    "inserted_at": "2024-02-05T18:48:35.636805",
    "id": "a7ade569-2c89-40b4-8ec4-65a30cb7eacf",
    "from_credit_card": {
      "status": "tokenized",
      "inserted_at": "2024-02-05T18:48:35.634459",
      "id": "34193f52-1a40-4d32-a97f-e3658f6b8625"
    },
    "from_bank_account": null,
    "for_exchange": true,
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "currency": "MXN",
    "cleared": true,
    "bank_transaction": null
  }
}

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required
`threeds`	An object containing only the jwt token. You will get that token on the front-end	object	true

Test Cards

Card Numbers	Description
`4456528080389860`, `4456529267234200`, `4456529165328302`, `4456524869770255`	Valid test cards that will trigger the 3ds OTP validation (must be above 1000 MXN)
`4456540000000063`, `4456541249811088`, `4456543371713314`, `4456541982068615`	Valid test cards that will always approve, skipping the 3ds OTP validation
`4456530000000031`, `4456530000000106`, `4456536583667765`, `4456536501449767`	Test cards that will fail the 3DS validation
`4456523340069956`, `4456541249811088`	Test cards that will always fail
`4349003000047015`, `4349001210846432`, `4349001386781322`, `4349003243371321`	Test cards that will always fail and the reason will be disclosed

Confirm 3DS Credit Card Transaction in Mexico 🇲🇽

When your customer is prompted for an OTP, the transaction you created in the previous step will be held on pending until this step is done. Once that OTP is entered and confirmed, this endpoint needs to be called in the sequence. If the process is successfully complete, you will have an identified status transaction. Otherwise, it will be canceled. In this case you can check what happened in the errors or payment_failed field. Note: if you are using our HTML sample page, this part will be done automatically and any errors will be presented on pop-ups.

curl -X POST "https://api.facilitapay.com/api/v1/transactions/:id/confirm_threeds" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."

200OK

{
  "data": {
    "value": "2000.00",
    "to_bank_account": {
      "routing_number": "Further Credit To / REF: SWS2319371",
      "pix_info": null,
      "owner_name": "REARDEN STEEL CO. Ltd.",
      "owner_document_number": "2348909854385",
      "owner_company": {
        "social_name": "POWER HOME THEATER",
        "id": "f64e512c-1a81-42d9-9ac9-05f369bc98e3",
        "document_type": "tax_id",
        "document_number": "2348909854385"
      },
      "nickname": "Power Conta 1",
      "intermediary_bank_account": null,
      "id": "a1db04a1-ddc9-4aa8-a0a5-2c74cf9505d0",
      "iban": null,
      "currency": "USD",
      "branch_number": null,
      "branch_country": "MEX",
      "bank": {
        "swift": "MT2502041",
        "name": "M&T Bank",
        "id": "d6f801e9-57c0-43af-8b11-07b8bd4fff0f",
        "country": null,
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": "00416612332",
      "aba": null
    },
    "subject_is_receiver": false,
    "subject_id": "9e474282-8b37-4d05-9c77-eab27976cfe9",
    "subject": {
      "updated_at": "2024-02-05T19:20:24.196893",
      "status": "approved",
      "social_name": "HORACIO SOTO MORALES",
      "rfc_pf": null,
      "required_clearance_level": 2,
      "phone_number": "434898404898",
      "net_monthly_average_income": "50000.00",
      "inserted_at": "2021-03-26T20:22:04.358980",
      "id": "9e474282-8b37-4d05-9c77-eab27976cfe9",
      "fiscal_country": "Mexico",
      "email": "[email protected]",
      "document_type": "curp",
      "document_number": "SOMH031031HSRTRRA3",
      "clearance_level": 2,
      "birth_date": null,
      "address_street": "Calle Cannobio",
      "address_state": "PS",
      "address_postal_code": "39847389",
      "address_number": "75",
      "address_neighborhood": "Aldea Alpina",
      "address_country": "Mexico",
      "address_complement": "",
      "address_city": "Nuova Lima"
    },
    "status": "identified",
    "source_name": "HORACIO SOTO MORALES",
    "source_document_type": "curp",
    "source_document_number": "SOMH031031HSRTRRA3",
    "meta": null,
    "inserted_at": "2024-02-05T19:20:24.172547",
    "id": "a7ade569-2c89-40b4-8ec4-65a30cb7eacf",
    "from_credit_card": {
      "status": "tokenized",
      "inserted_at": "2024-02-05T19:20:24.171366",
      "id": "5a5aa8b2-fcf1-4e98-85a3-e349cd72c374"
    },
    "from_bank_account": null,
    "for_exchange": true,
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "currency": "MXN",
    "cleared": true,
    "bank_transaction": {
      "wire_id": null,
      "value": "2002.0",
      "spei_reference": null,
      "spei_concepto_de_pago": null,
      "source_type": "CREDIT CARD",
      "source_name": "HORACIO SOTO MORALES",
      "source_id": "48a01ee3-5132-41b7-8f07-7248a1101374",
      "source_document_type": "curp",
      "source_document_number": "SOMH031031HSRTRRA3",
      "source_description": "PAGAMENTO POR CARTAO",
      "source_branch": null,
      "source_bank": null,
      "source_account": null,
      "movement_date": "2024-02-05",
      "iof_value": null,
      "inserted_at": "2024-02-05T19:23:55.510552",
      "id": "a081e257-cfeb-4aea-9f77-e8b8bf8682ed",
      "exchanged_value": null,
      "exchange_rate_spot": null,
      "exchange_rate": null,
      "exchange_id": null,
      "exchange_currency": "USD",
      "exchange_approved": false,
      "currency": "MXN"
    }
  }
}

HTTP Request

POST /transactions/:id/confirm_threeds

Path Parameters

Parameter	Description	Type	Required
`id`	ID of the transaction created in the previous step	string	true

Credit card transactions in Colombia 🇨🇴

Supported brands: Mastercard and Visa

For Colombia you will create a credit card transaction calling our API, using the from_credit_card field. Check the payload below.

We highly recommend testing the checkout page first before initiating direct API calls, because you can adapt it to your front-end environment.

To create using the API call you will use the following endpoint:

Download sample page

curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "transaction": {
    "currency": "COP",
    "exchange_currency": "USD",
    "value": "2000000.00",
    "from_credit_card": {
      "card_number": "4456524869770255",
      "card_expiration_date": "03/27",
      "card_security_code": "234",
      "card_brand": "Visa",
      "card_type": "Credit",
      "fullname": "Luiz Abreu Nieto"
    },
    "threeds": { "jwt": "eyJhbGciOiJIUzI1NiIsInR5cC..."
    },
    "to_bank_account_id": "{{partner_usd_account_id}}",
    "subject_id": "{{co_person_id}}"
  }
}'

200OK

{
  "data": {
    "value": "2000000.00",
    "to_bank_account": {
      "routing_number": "Further Credit To / REF: SWS2319371",
      "pix_info": null,
      "owner_name": "REARDEN STEEL CO. Ltd.",
      "owner_document_number": "2348909854385",
      "owner_company": {
        "social_name": "POWER HOME THEATER",
        "id": "f64e512c-1a81-42d9-9ac9-05f369bc98e3",
        "document_type": "tax_id",
        "document_number": "2348909854385"
      },
      "nickname": "Power Conta 1",
      "intermediary_bank_account": null,
      "id": "a1db04a1-ddc9-4aa8-a0a5-2c74cf9505d0",
      "iban": null,
      "currency": "USD",
      "branch_number": null,
      "branch_country": "USD",
      "bank": {
        "swift": "MT2502041",
        "name": "M&T Bank",
        "id": "d6f801e9-57c0-43af-8b11-07b8bd4fff0f",
        "country": null,
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": "00416612332",
      "aba": null
    },
    "threeds_data": {
      "three_ds_version": "1.0.2",
      "secure_id": "1bff5e25-6cac-4f59-8670-fbce6d00762b",
      "pareq": "sandbox",
      "authentication_transaction_id": "OWgXwASsYPW4hr1ATcf0",
      "acs_url": ""
    },
    "subject_is_receiver": false,
    "subject_id": "9e474282-8b37-4d05-9c77-eab27976cfe9",
    "subject": {
      "updated_at": "2024-02-05T18:48:35.654100",
      "status": "approved",
      "social_name": "HORACIO SOTO MORALES",
      "rfc_pf": null,
      "required_clearance_level": 2,
      "references": [],
      "phone_number": "434898404898",
      "net_monthly_average_income": "50000.00",
      "inserted_at": "2021-03-26T20:22:04.358980",
      "id": "9e474282-8b37-4d05-9c77-eab27976cfe9",
      "fiscal_country": "Colombia",
      "email": "[email protected]",
      "document_type": "cc",
      "document_number": "1037633285",
      "clearance_level": 2,
      "birth_date": null,
      "address_street": "Calle Cannobio",
      "address_state": "PS",
      "address_postal_code": "39847389",
      "address_number": "75",
      "address_neighborhood": "Aldea Alpina",
      "address_country": "Mexico",
      "address_complement": "",
      "address_city": "Nuova Lima"
    },
    "status": "pending",
    "source_name": "HORACIO SOTO MORALES",
    "source_document_type": "cc",
    "source_document_number": "1037633285",
    "payment_method": null,
    "meta": null,
    "inserted_at": "2024-02-05T18:48:35.636805",
    "id": "a7ade569-2c89-40b4-8ec4-65a30cb7eacf",
    "from_credit_card": {
      "status": "tokenized",
      "inserted_at": "2024-02-05T18:48:35.634459",
      "id": "34193f52-1a40-4d32-a97f-e3658f6b8625"
    },
    "from_bank_account": null,
    "for_exchange": true,
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "currency": "COP",
    "cleared": true,
    "bank_transaction": null
  }
}

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required
`threeds`	An object containing only the jwt token. You will get that token on the front-end	object	true

Test Cards

Card Numbers	Description
`4456528080389860`, `4456529267234200`, `4456529165328302`, `4456524869770255`	Valid test cards that will trigger the 3ds OTP validation (must be above 100,000 COP)
`4456540000000063`, `4456540000000064`, `4456543371713314`, `4456541982068615`	Valid test cards that will skip the 3ds OTP validation regardless of the value
`4456523340069956`, `4456541249811088`	Test cards that will always fail
`4349003000047015`, `4349001210846432`, `4349001386781322`, `4349003243371321`	Test cards that will always fail and the reason will be disclosed

Confirm 3DS Credit Card Transaction in Colombia 🇨🇴

When your customer is prompted for an OTP (one-time password), the transaction you created in the previous step will be held on pending until this step is done. Once that OTP is entered and confirmed, this endpoint needs to be called in the sequence. If the process is successfully complete, you will have an identified status transaction. Otherwise, it will be canceled. In this case you can check what happened in the errors or payment_failed field. Note: if you are using the HTML sample page, this part will be done automatically and any errors will be presented on pop-ups. Notice that in sandbox, this scenario can be simulated by making a transaction greater than 100000 COP.

curl -X POST "https://api.facilitapay.com/api/v1/transactions/:id/confirm_threeds" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."

200OK

{
  "data": {
    "value": "200000.00",
    "to_bank_account": {
      "routing_number": "Further Credit To / REF: SWS2319371",
      "pix_info": null,
      "owner_name": "REARDEN STEEL CO. Ltd.",
      "owner_document_number": "2348909854385",
      "owner_company": {
        "social_name": "POWER HOME THEATER",
        "id": "f64e512c-1a81-42d9-9ac9-05f369bc98e3",
        "document_type": "tax_id",
        "document_number": "2348909854385"
      },
      "nickname": "Power Conta 1",
      "intermediary_bank_account": null,
      "id": "a1db04a1-ddc9-4aa8-a0a5-2c74cf9505d0",
      "iban": null,
      "currency": "USD",
      "branch_number": null,
      "branch_country": "COL",
      "bank": {
        "swift": "MT2502041",
        "name": "M&T Bank",
        "id": "d6f801e9-57c0-43af-8b11-07b8bd4fff0f",
        "country": null,
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": "00416612332",
      "aba": null
    },
    "subject_is_receiver": false,
    "subject_id": "9e474282-8b37-4d05-9c77-eab27976cfe9",
    "subject": {
      "updated_at": "2024-02-05T19:20:24.196893",
      "status": "approved",
      "social_name": "HORACIO SOTO MORALES",
      "rfc_pf": null,
      "required_clearance_level": 2,
      "phone_number": "434898404898",
      "net_monthly_average_income": "50000.00",
      "inserted_at": "2021-03-26T20:22:04.358980",
      "id": "9e474282-8b37-4d05-9c77-eab27976cfe9",
      "fiscal_country": "Colombia",
      "email": "[email protected]",
      "document_type": "cc",
      "document_number": "1037633285",
      "clearance_level": 2,
      "birth_date": null,
      "address_street": "Calle Cannobio",
      "address_state": "PS",
      "address_postal_code": "39847389",
      "address_number": "75",
      "address_neighborhood": "Aldea Alpina",
      "address_country": "Colombia",
      "address_complement": "",
      "address_city": "Nuova Lima"
    },
    "status": "identified",
    "source_name": "HORACIO SOTO MORALES",
    "source_document_type": "cc",
    "source_document_number": "1037633285",
    "meta": null,
    "inserted_at": "2024-02-05T19:20:24.172547",
    "id": "a7ade569-2c89-40b4-8ec4-65a30cb7eacf",
    "from_credit_card": {
      "status": "tokenized",
      "inserted_at": "2024-02-05T19:20:24.171366",
      "id": "5a5aa8b2-fcf1-4e98-85a3-e349cd72c374"
    },
    "from_bank_account": null,
    "for_exchange": true,
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "currency": "COP",
    "cleared": true,
    "bank_transaction": {
      "wire_id": null,
      "value": "2002.0",
      "spei_reference": null,
      "spei_concepto_de_pago": null,
      "source_type": "CREDIT CARD",
      "source_name": "HORACIO SOTO MORALES",
      "source_id": "48a01ee3-5132-41b7-8f07-7248a1101374",
      "source_document_type": "cc",
      "source_document_number": "1037633285",
      "source_description": "PAGAMENTO POR CARTAO",
      "source_branch": null,
      "source_bank": null,
      "source_account": null,
      "movement_date": "2024-02-05",
      "iof_value": null,
      "inserted_at": "2024-02-05T19:23:55.510552",
      "id": "a081e257-cfeb-4aea-9f77-e8b8bf8682ed",
      "exchanged_value": null,
      "exchange_rate_spot": null,
      "exchange_rate": null,
      "exchange_id": null,
      "exchange_currency": "USD",
      "exchange_approved": false,
      "currency": "COP"
    }
  }
}

HTTP Request

POST /transactions/:id/confirm_threeds

Path Parameters

Parameter	Description	Type	Required
`id`	ID of the transaction created in the previous step	string	true

Credit card transactions in Chile 🇨🇱

Supported brands: Mastercard and Visa

To create transactions using a Chilean credit card, you have two options: utilize the provided API call, exemplified below, or opt for the checkout page sample available on our sandbox portal or via the following link. We highly recommend testing the checkout page first before initiating direct API calls, because you can adapt it to your front-end environment.

There are also 2 possible flows for payment: one-time payment and tokenization, each one with a full working HTML example. You can find further instructions on the HTML sample pages.

Check in the person or company sections for the required information you need to collect from your customers to enable the creation of a card transaction since the 3DS validation is implemented in CLP card transactions.

To create using the API call you will use the following endpoint:

Download sample page

curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "transaction": {
    "currency": "CLP",
    "exchange_currency": "USD",
    "value": "30000",
    "from_credit_card": {
      "card_number": "4456524869770255",
      "card_expiration_date": "03/30",
      "card_security_code": "345",
      "card_brand": "Visa",
      "fullname": "Muñoz Perez Izidro"
    },
    "threeds": {
      "jwt": "eyJhbGciOiJIUzI1NiIsInR5cC..."
    },
    "to_bank_account_id": "{{partner_usd_account_id}}",
    "subject_id": "{{cl_person_id}}"
  }
}'

200OK

{
  "data": {
    "value": "30000",
    "to_bank_account": {
      "routing_number": "021000021 - Special instruction: SFTB000001",
      "pix_info": null,
      "owner_name": null,
      "owner_document_type": null,
      "owner_document_number": null,
      "owner_company": {
        "social_name": "POWER HOME THEATER",
        "id": "f64e512c-1a81-42d9-9ac9-05f369bc98e3",
        "document_type": "tax_id",
        "document_number": "2348909854385"
      },
      "nickname": null,
      "intermediary_bank_account": null,
      "id": "4af245f8-de8b-45f5-8ba7-58003d325b12",
      "iban": null,
      "currency": "USD",
      "branch_number": null,
      "branch_country": "CHL",
      "bank": {
        "swift": "CHASUS33",
        "name": "JPMorgan Chase Bank",
        "ispb": null,
        "id": "e6a25c9c-e5f2-49db-a24e-c8710a18b6a8",
        "country": null,
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": "10000344906926",
      "aba": null
    },
    "threeds_challenge": {
      "three_ds_version": "1.0.2",
      "secure_id": "3a141ce3-cc10-4793-97b6-acc709d262a8",
      "pareq": "sandbox",
      "authentication_transaction_id": "OWgXwASsYPW4hr1ATcf0",
      "auth_required": true,
      "acs_url": ""
    },
    "subject_is_receiver": false,
    "subject_id": "4a42a549-09fa-489f-a22a-3557d2323443",
    "subject": {
      "updated_at": "2025-07-10T22:02:08.671256",
      "status": "approved",
      "social_name": "Muñoz Perez",
      "required_clearance_level": 1,
      "references": [],
      "phone_number": "675675",
      "phone_country_code": "32",
      "phone_area_code": "56",
      "partners": [],
      "net_value": "0.00",
      "net_monthly_average_income": "0.00",
      "natural_person": true,
      "main_activity": null,
      "inserted_at": "2025-02-14T12:15:40.779049",
      "id": "4a42a549-09fa-489f-a22a-3557d2323443",
      "fiscal_country": "Chile",
      "email": "[email protected]",
      "document_type": "rut",
      "document_number": "112934596",
      "creation_date": "1994-09-18",
      "company_type": "ltda",
      "company_name": "Muñoz Perez",
      "clearance_level": 1,
      "address_street": "Parcela 1 Sector Huaqui Los Angeles",
      "address_state": "PQ",
      "address_postal_code": "64345",
      "address_number": "2251",
      "address_neighborhood": "Santa Ines",
      "address_country": "Chile",
      "address_complement": null,
      "address_city": "Sausalito",
      "activity_type": "outros"
    },
    "status": "pending",
    "source_name": "Muñoz Perez",
    "source_document_type": "rut",
    "source_document_number": "112934596",
    "payment_method": null,
    "meta": null,
    "inserted_at": "2025-07-10T22:02:08.659847",
    "id": "151e99e5-67c2-4e66-94c1-01849d8e8c43",
    "from_credit_card": {
      "status": "tokenized",
      "masked_card_number": "445652******0255",
      "inserted_at": "2025-07-10T22:02:08.658377",
      "id": "1c56114f-9805-480a-a46c-5782005ba6c9"
    },
    "from_bank_account": null,
    "for_exchange": true,
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "currency": "CLP",
    "cleared": true,
    "bank_transaction": null
  }
}

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required
`threeds`	An object containing only the jwt token. You will get that token on the front-end	object	true

Test Cards

Card Numbers	Description
`4456528080389860`, `4456529267234200`, `4456529165328302`, `4456524869770255`	Valid test cards that will trigger the 3ds OTP validation (must be above 100,000 COP)
`4456540000000063`, `4456540000000064`, `4456543371713314`, `4456541982068615`	Valid test cards that will skip the 3ds OTP validation regardless of the value
`4456523340069956`, `4456541249811088`	Test cards that will always fail
`4349003000047015`, `4349001210846432`, `4349001386781322`, `4349003243371321`	Test cards that will always fail and the reason will be disclosed

Confirm 3DS Credit Card Transaction in Chile 🇨🇱

If the process is successfully complete, you will have an identified status transaction. Otherwise, it will be canceled. In this case you can check what happened in the errors or payment_failed field.

Note: if you are using the HTML sample page, this part will be done automatically and any errors will be presented on pop-ups.

Notice that in sandbox, this scenario can be simulated by making a transaction greater than 3000 CLP.

curl -X POST "https://api.facilitapay.com/api/v1/transactions/:id/confirm_threeds" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."

200OK

{
  "data": {
    "value": "30000",
    "to_bank_account": {
      "routing_number": "021000021 - Special instruction: SFTB000001",
      "pix_info": null,
      "owner_name": null,
      "owner_document_type": null,
      "owner_document_number": null,
      "owner_company": {
        "social_name": "POWER HOME THEATER",
        "id": "f64e512c-1a81-42d9-9ac9-05f369bc98e3",
        "document_type": "tax_id",
        "document_number": "2348909854385"
      },
      "nickname": null,
      "intermediary_bank_account": null,
      "id": "4af245f8-de8b-45f5-8ba7-58003d325b12",
      "iban": null,
      "currency": "USD",
      "branch_number": null,
      "branch_country": "CHL",
      "bank": {
        "swift": "CHASUS33",
        "name": "JPMorgan Chase Bank",
        "ispb": null,
        "id": "e6a25c9c-e5f2-49db-a24e-c8710a18b6a8",
        "country": null,
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": "10000344906926",
      "aba": null
    },
    "subject_is_receiver": false,
    "subject_id": "4a42a549-09fa-489f-a22a-3557d2323443",
    "subject": {
      "updated_at": "2025-07-10T22:02:08.671256",
      "status": "approved",
      "social_name": "Muñoz Perez",
      "required_clearance_level": 1,
      "phone_number": "675675",
      "phone_country_code": "32",
      "phone_area_code": "56",
      "net_value": "0.00",
      "net_monthly_average_income": "0.00",
      "natural_person": true,
      "main_activity": null,
      "inserted_at": "2025-02-14T12:15:40.779049",
      "id": "4a42a549-09fa-489f-a22a-3557d2323443",
      "fiscal_country": "Chile",
      "email": "[email protected]",
      "document_type": "rut",
      "document_number": "112934596",
      "creation_date": "1994-09-18",
      "company_type": "ltda",
      "company_name": "Muñoz Perez",
      "clearance_level": 1,
      "address_street": "Parcela 1 Sector Huaqui Los Angeles",
      "address_state": "PQ",
      "address_postal_code": "64345",
      "address_number": "2251",
      "address_neighborhood": "Santa Ines",
      "address_country": "Chile",
      "address_complement": null,
      "address_city": "Sausalito",
      "activity_type": "outros"
    },
    "status": "identified",
    "source_name": "Muñoz Perez",
    "source_document_type": "rut",
    "source_document_number": "112934596",
    "meta": null,
    "inserted_at": "2025-07-10T22:02:08.659847",
    "id": "151e99e5-67c2-4e66-94c1-01849d8e8c43",
    "from_credit_card": {
      "status": "tokenized",
      "masked_card_number": "445652******0255",
      "inserted_at": "2025-07-10T22:02:08.658377",
      "id": "1c56114f-9805-480a-a46c-5782005ba6c9"
    },
    "from_bank_account": null,
    "for_exchange": true,
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "currency": "CLP",
    "cleared": true,
    "bank_transaction": {
      "wire_id": null,
      "value": "30000.0",
      "spei_reference": null,
      "spei_concepto_de_pago": null,
      "source_type": "CREDIT CARD",
      "source_name": "Muñoz Perez",
      "source_id": "151e99e5-67c2-4e66-94c1-01849d8e8c43",
      "source_document_type": "rut",
      "source_document_number": "112934596",
      "source_description": "PAGAMENTO POR CARTAO",
      "source_branch": null,
      "source_bank_ispb": null,
      "source_bank": null,
      "source_account": null,
      "movement_date": "2025-07-10",
      "iof_value": null,
      "inserted_at": "2025-07-10T22:02:22.411691",
      "id": "455987dd-605f-493f-811f-251a32da1689",
      "exchanged_value": null,
      "exchange_rate_spot": null,
      "exchange_rate": null,
      "exchange_id": null,
      "exchange_currency": "USD",
      "exchange_approved": false,
      "currency": "CLP"
    }
  }
}

HTTP Request

POST /transactions/:id/confirm_threeds

Path Parameters

Parameter	Description	Type	Required
`id`	ID of the transaction created in the previous step	string	true

Card Tokenization​

HTTP Request​

Path Parameters​

Body Parameters​

Confirm Card Tokenization​

HTTP Request​

Path Parameters​

Body Parameters​

Example - Credit Card Transaction​

HTTP Request​

Body Parameters​

Credit card transactions in Brazil 🇧🇷​

HTTP Request​

Body Parameters​

Test Cards​

Important Notes​

Troubleshooting​

Credit card transactions in Brazil 🇧🇷 - JWT for DDC​

HTTP Request​

Credit card transactions in Mexico 🇲🇽​

HTTP Request​

Body Parameters​

Test Cards​

Confirm 3DS Credit Card Transaction in Mexico 🇲🇽​

HTTP Request​

Path Parameters​

Credit card transactions in Colombia 🇨🇴​

HTTP Request​

Body Parameters​

Test Cards​

Confirm 3DS Credit Card Transaction in Colombia 🇨🇴​

HTTP Request​

Path Parameters​

Credit card transactions in Chile 🇨🇱​

HTTP Request​

Body Parameters​

Test Cards​

Confirm 3DS Credit Card Transaction in Chile 🇨🇱​

HTTP Request​

Path Parameters​

Card Tokenization

HTTP Request

Path Parameters

Body Parameters

Confirm Card Tokenization

HTTP Request

Path Parameters

Body Parameters

Example - Credit Card Transaction

HTTP Request

Body Parameters

Credit card transactions in Brazil 🇧🇷

HTTP Request

Body Parameters

Test Cards

Important Notes

Troubleshooting

Credit card transactions in Brazil 🇧🇷 - JWT for DDC

HTTP Request

Credit card transactions in Mexico 🇲🇽

HTTP Request

Body Parameters

Test Cards

Confirm 3DS Credit Card Transaction in Mexico 🇲🇽

HTTP Request

Path Parameters

Credit card transactions in Colombia 🇨🇴

HTTP Request

Body Parameters

Test Cards

Confirm 3DS Credit Card Transaction in Colombia 🇨🇴

HTTP Request

Path Parameters

Credit card transactions in Chile 🇨🇱

HTTP Request

Body Parameters

Test Cards

Confirm 3DS Credit Card Transaction in Chile 🇨🇱

HTTP Request

Path Parameters