Overview

This document outlines the process for initiating a transaction through the Facilero API. By using the provided curl command, you can make a POST request to start the transaction. Once the request is processed, a webhook will deliver the transaction details to your server. If 3D Secure authentication is required, the client will need to be redirected to complete the process.

API Endpoint

Live

POST https://live.facilero.com/api/v1/payments/card

Sandbox

POST https://sandbox.facilero.com/api/v1/payments/card

Request Headers

Content-Type: application/json
Authorization: Bearer <AUTH_TOKEN>
Replace <AUTH_TOKEN> with the actual token obtained from the Authorization Service.
Referer: <REFERER_URL>
Replace <REFERER_URL> with the relevant referring URL.

Request Body

Fields

Field	Type	Required	Description
`requestId`	String	Yes	Unique ID for the payment request.
`mid`	String	Yes	Merchant account ID to which the transaction will be associated.
`card`	Object (Card)	Yes	Contains card details (see Card Object).
`amount`	String	Yes	Transaction amount as a string. Follow currency precision rules.
`currency`	String	Yes	ISO 4217 currency code (e.g., USD, EUR).
`lang`	String	Yes	Language code for communication.
`callbackUrl`	String	No	URL for receiving transaction status updates. Required for 3D transactions (`requestThreeDSecure = true`).
`successRedirectUrl`	String	No	URL to redirect the customer after a successful payment. Required for 3D transactions (`requestThreeDSecure = true`).
`failureRedirectUrl`	String	No	URL to redirect the customer after a failed payment. Required for 3D transactions (`requestThreeDSecure = true`).
`billingDetails`	Object (BillingDetails)	Yes	Contains billing details such as name, address, and contact info (see BillingDetails Object).
`order`	Object (Order)	Yes	Contains order information (see Order Object).
`device`	Object (Device)	Yes	Contains device information for risk assessment (see Device Object).
`kycVerified`	Boolean	No	Indicates if the customer has been KYC (Know Your Customer) verified.
`previousPaymentCount`	Long	No	Number of previous payments (for First-Time Deposit (FTD) calculations).
`metadata`	Map<String, String>	No	Additional key-value metadata for custom use.

Card Object

Field	Type	Required	Description
`number`	String	Yes	Card number in string format.
`cardHolderName`	String	No	Name of the cardholder as printed on the card.
`expMonth`	String	Yes	Expiration month of the card (MM format).
`expYear`	String	Yes	Expiration year of the card (YYYY format).
`cvv`	String	Yes	Card verification code (CVV/CVC).
`requestThreeDSecure`	Boolean	Yes	Indicates whether 3D Secure is required.

BillingDetails Object

Field	Type	Required	Description
`externalUserId`	String	No	External identifier for the customer in your system.
`firstName`	String	Yes	First name of the customer.
`lastName`	String	Yes	Last name of the customer.
`address1`	String	Yes	Billing address line 1.
`city`	String	Yes	Billing city.
`state`	String	Yes	Billing state or province.
`country`	String	Yes	Billing country (ISO Alpha-2 format, e.g., US, FR).
`postalCode`	String	Yes	Postal code.
`phone`	String	No	Customer’s phone number.
`email`	String	Yes	Customer’s email address.
`dateOfBirth`	String	Yes	Customer’s date of birth (YYYY-MM-DD format).

Order Object

Field	Type	Required	Description
`date`	String	No	Date of the order.
`orderId`	String	No	Unique identifier for the order.
`title`	String	No	Title or name of the order.
`siteId`	String	No	Site identifier where the order was placed.
`name`	String	No	Customer's name for the order.
`domainName`	String	No	Domain name where the order was placed.

Device Object

Field	Type	Required	Description
`deviceId`	String	No	Unique identifier for the device.
`fingerprintData`	String	No	Device fingerprint data for risk assessment.
`ip`	String	Yes	Customer's IP address.
`accept`	String	No	Browser's accept header. Required for 3D Secure transactions
`acceptLanguage`	String	No	Language accepted by the browser. Required for 3D Secure transactions
`userAgent`	String	Yes	User-Agent header for identifying the browser.
`javaEnabled`	Boolean	No	Flag indicating whether Java is enabled. Required for 3D Secure transactions
`javaScriptEnabled`	Boolean	No	Flag indicating whether JavaScript is enabled. Required for 3D Secure transactions
`deviceLanguage`	String	No	Language set on the device. Required for 3D Secure transactions
`colorDepth`	String	No	Screen color depth in bits. Required for 3D Secure transactions
`screenHeight`	String	No	Screen height in pixels. Required for 3D Secure transactions
`screenWidth`	String	No	Screen width in pixels. Required for 3D Secure transactions
`deviceTimezone`	String	No	Timezone of the device. Required for 3D Secure transactions

Example Request Body

{
  "requestId": "req12345",
  "mid": "merchant456",
  "card": {
    "number": "4111111111111111",
    "cardHolderName": "John Doe",
    "expMonth": "12",
    "expYear": "2025",
    "cvv": "123",
    "requestThreeDSecure": true
  },
  "amount": "100.00",
  "currency": "USD",
  "lang": "en",
  "callbackUrl": "https://yourserver.com/callback",
  "successRedirectUrl": "https://yourserver.com/success",
  "failureRedirectUrl": "https://yourserver.com/failure",
  "billingDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "postalCode": "10001",
    "phone": "+123456789",
    "email": "[email protected]"
  },
  "order": {
    "date": "2024-10-10",
    "orderId": "ord789",
    "title": "Product Purchase",
    "siteId": "site001",
    "name": "John Doe",
    "domainName": "example.com"
  },
  "device": {
    "deviceId": "device123",
    "fingerprintData": "fingerprintData",
    "ip": "192.168.1.1",
    "accept": "*/*",
    "acceptLanguage": "en-US",
    "userAgent": "Mozilla/5.0",
    "javaEnabled": true,
    "javaScriptEnabled": true,
    "deviceLanguage": "en",
    "colorDepth": "24",
    "screenHeight": "1080",
    "screenWidth": "1920",
    "deviceTimezone": "America/New_York"
  },
  "kycVerified": true,
  "previousPaymentCount": 5,
  "metadata": {
    "customKey1": "customValue1",
    "customKey2": "customValue2"
  }
}

Response Body

Field	Type	Required	Description
`transactionId`	String	Yes	Unique identifier for the transaction.
`transactionStatus`	String	Yes	Current status of the transaction (e.g., NEW, PENDING, FAILED, REFUNDED, etc.).
`declineCode`	Int	No	Decline code if the transaction fails.
`challengeUrl`	String	No	URL for the 3D Secure challenge (if required for redirection).
`challengeUrlIframe`	String	No	URL for embedding the 3D Secure challenge in an iframe (if supported).

Example Response Body

Successful Response Example:

{
  "transactionId": "txn12345",
  "transactionStatus": "SUCCEED",
}

Failed Response Example:

{
  "transactionId": "txn67890",
  "transactionStatus": "FAILED",
  "declineCode": 101
}

3D Secure Challenge Example:

supporting iframe

{
  "transactionId": "txn11223",
  "transactionStatus": "CUSTOMER_VERIFICATION",
  "challengeUrl": "https://secure-3ds-url.com/challenge",
  "challengeUrlIframe": "https://secure-3ds-url.com/iframe-challenge"
}

Not Supporting Iframe

{
  "transactionId": "txn11223",
  "transactionStatus": "CUSTOMER_VERIFICATION",
  "challengeUrl": "https://secure-3ds-url.com/challenge",
}

Merchant Callback DTO

The Merchant Callback DTO represents the structure of the callback data sent to the callbackUrl specified in the payment request. This object contains details about the transaction and its status.

Fields

Field	Type	Required	Description
`transactionId`	String	Yes	Unique identifier for the transaction.
`requestId`	String	Yes	The original request ID provided when initiating the transaction.
`mid`	String	Yes	Merchant ID associated with the transaction.
`transactionStatus`	Enum (TxStatus)	Yes	The status of the transaction (e.g., SUCCEED, FAILED, PENDING).
`declineCode`	Integer	No	Code indicating the reason for transaction failure (if applicable).
`cardMask`	String	Yes	Masked card number (e.g., 4111********1111).
`cardHolder`	String	No	Name of the cardholder (if available).
`orderCurrency`	String	Yes	The currency of the original order, represented as an ISO 4217 code.
`processedCurrency`	String	Yes	The currency in which the transaction was processed, as an ISO 4217 code.
`orderAmount`	Double	Yes	The original amount of the transaction in the order currency.
`processedAmount`	Double	Yes	The amount processed in the processed currency.
`conversionRate`	Double	Yes	The conversion rate applied for currency exchange (if applicable).
`callbackUrl`	String	No	The URL where the callback was sent.
`billingDetails`	Object (BillingDetails)	Yes	Details of the customer’s billing information (see BillingDetails object).
`order`	Object (Order)	Yes	Information about the associated order (see Order object).
`createdAt`	String	Yes	Timestamp when the transaction was created.

Example Callback Object

{
  "transactionId": "txn12345",
  "requestId": "req67890",
  "mid": "merchant001",
  "transactionStatus": "SUCCEED",
  "declineCode": null,
  "cardMask": "411111******1111",
  "cardHolder": "John Doe",
  "orderCurrency": "USD",
  "processedCurrency": "USD",
  "orderAmount": 100.0,
  "processedAmount": 100.0,
  "conversionRate": 1.0,
  "callbackUrl": "https://yourserver.com/callback",
  "billingDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "country": "US",
    "email": "[email protected]"
  },
  "order": {
    "orderId": "order789",
    "title": "Product Purchase"
  },
  "createdAt": "2024-01-01T12:00:00Z"
}

Completing the Payment

After receiving the webhook, you need to redirect the client to the 3dsRedirectUrl to complete the payment. Once the 3DS process is finished, the client will be redirected to the callback URL if successful, or to the callbackFail URL if the payment fails.

Ensure that all required fields are filled correctly to avoid transaction issues.

This documentation provides an overview of creating a transaction using the Facilero API, handling callbacks, and redirecting the client for 3DS authentication.

⚠️ Important Note on Amount Formatting

The Card Payment API does not use a checksum mechanism, however merchants should still be aware of the following formatting detail:

In requests, the amount field is provided as a string (e.g., "200.00").
In callbacks, the amount fields (orderAmount, processedAmount) are returned as double values (e.g., 200.0).

Because Facilero uses native numeric types internally, trailing zeros after the decimal point may not be preserved. This is expected behavior and does not indicate a data mismatch.

👉 Merchants should always use the amount value provided in the callback when performing validations or reconciliation, rather than comparing against the raw string format from the original request.