One-Click Payment API

This endpoint allows you to charge a customer’s card using a previously generated token (from the tokenize
endpoint). It creates a payment transaction similar to the standard card payment initiation, but instead of
raw card details, you supply the token.

Overview

This endpoint mirrors the /payments/card flow but replaces the card object with a cardToken. All redirects, webhooks, risk checks and 3DS handling remain unchanged.
The cardToken is obtained via the Tokenization API, and you supply the same rich metadata you’d use for a standard Card-Sale:

Risk & SCA via device
Order tracking via order
Customer info via billingDetails
Custom flags via metadata

API Endpoint

Live

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

Sandbox

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

Request Headers

Content-Type: application/json
Authorization: Bearer <AUTH_TOKEN>
Referer: <REFERER_URL>

Request Body

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.
`cardToken`	String	Yes	Vaulted token obtained from the Tokenization API.
`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	No	Language code for communication (e.g., `en`, `fr`).
`callbackUrl`	String	Yes	URL for receiving transaction status updates. Required for 3DS flows.
`successRedirectUrl`	String	Yes	URL to redirect the customer after a successful payment (3DS).
`failureRedirectUrl`	String	Yes	URL to redirect the customer after a failed payment (3DS).
`billingDetails`	Object (BillingDetails)	No	Customer’s name, address, contact info. If omitted, uses billing details from the original tokenization request.
`order`	Object (Order)	No	Order date, ID, title, site, customer name, domain. Defaults to empty if omitted.
`device`	Object (Device)	No	IP, UA, headers, 3DS device data. Defaults to server IP if omitted.
`kycVerified`	Boolean	No	Indicates if the customer has already been KYC-verified.
`previousPaymentCount`	Long	No	Number of previous payments by this customer.
`metadata`	Map<String, String>	No	Additional key/value metadata for custom use.

Note: The BillingDetails, Order, and Device objects are exactly the same as in the Card-Sale API. Refer to those definitions for field-level details.

Tip: Since billing details are stored during tokenization, you can omit billingDetails on subsequent charges — the system will automatically use the details provided when the card was tokenized. Pass billingDetails only if you need to override them for a specific charge (e.g., the customer updated their address).

Example Request Body

{
  "requestId":           "req-oneclick-456",
  "mid":                 "merchant456",
  "cardToken":           "tok_abc123xyz",
  "amount":              "50.00",
  "currency":            "EUR",
  "lang":                "en",
  "callbackUrl":         "https://yourserver.com/callback",
  "successRedirectUrl":  "https://yourserver.com/success",
  "failureRedirectUrl":  "https://yourserver.com/failure",
  "billingDetails": {
    "firstName":      "Jane",
    "lastName":       "Doe",
    "address1":       "123 Main St",
    "city":           "Dublin",
    "state":          "Leinster",
    "country":        "IE",
    "postalCode":     "D01X0F5",
    "phone":          "+353851234567",
    "email":          "[email protected]",
    "dateOfBirth":    "1990-05-20"
  },
  "order": {
    "date":       "2025-07-14",
    "orderId":    "ord-101",
    "title":      "One-Click Purchase",
    "siteId":     "site001",
    "name":       "Jane Doe",
    "domainName": "example.com"
  },
  "device": {
    "ip":                "203.0.113.42",
    "userAgent":         "Mozilla/5.0",
    "accept":            "*/*",
    "acceptLanguage":    "en-IE",
    "javaEnabled":       true,
    "javaScriptEnabled": true,
    "deviceLanguage":    "en",
    "colorDepth":        "24",
    "screenHeight":      "1080",
    "screenWidth":       "1920",
    "deviceTimezone":    "Europe/Dublin"
  },
  "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 (`NEW`, `PENDING`, `SUCCEED`, `FAILED`, `CUSTOMER_VERIFICATION`).
`declineCode`	Int	No	Scheme decline code if the transaction fails.
`challengeUrl`	String	No	URL for the 3D Secure challenge, if required.
`challengeUrlIframe`	String	No	Iframe-compatible 3DS URL, if supported.

Example Success Response

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

Example 3DS Challenge Response

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

Merchant Callback DTO

Identical to the Card-Sale callback.

Explanation:
By substituting cardToken for the raw card object in your existing Card-Sale integration, you maintain the exact same data model for billing, order tracking, device risk assessment, 3DS flows, and webhooks—while reducing your PCI footprint to token-only operations.

Error Responses

HTTP Status	Scenario	Example `errorMessage`
400	Token not found, expired, or inactive	`Token not found or expired: tok_xxxx****`
400	Billing details missing from both request & token	`Billing details missing from both request and token`
400	Invalid or missing required fields	`Missing required field: cardToken`

Important Notes

The response format, webhooks, and transaction lifecycle are identical to the standard card payment flow — same HppPaymentResponse, same callback DTOs, same 3DS handling.
After token resolution, the charge follows the exact same PSP orchestration pipeline as a regular /v1/payments/card request.
In sandbox, test cards from the Tokenization docs determine charge behavior (success, 3DS, decline).