Card payments (hosted checkout)

Card payments always go through Cashela’s hosted payment page (checkout). Your customer enters the card on a Cashela page, so card data never touches your systems and you do not need to handle PCI scope for it.

Choose a card option

1. Call Get payment methods for the country and amount.
2. Look for the CREDIT_CARD payment type. Its options are per card brand, for example international-credit-debit-card-visa, international-credit-debit-card-mastercard, international-credit-debit-card-amex or international-credit-debit-card-discover. The codes and brands available depend on your account and country: use the ones the catalog returns.
3. Let your customer choose the brand they will pay with.

The option is per brand

The payment page only accepts the brand of the option you chose. A Mastercard cannot pay a deposit created with a Visa option. If your customer changes their mind, create a new deposit with the right option.

Two kinds of card option

	Charged in USD	Charged in local currency
How to recognise it	The option carries charge_breakdown (always USD) and local_estimate	The option’s amounts are in the country’s currency (payment_info)
What your customer sees	The amount in USD and an estimate in local currency	The amount and fee in local currency
What the card is charged	USD. The card issuer sets the final exchange rate on your customer’s statement.	Local currency

For options charged in USD:

• The local-currency amount (local_estimate, and details.invoice_* on the deposit) is informative only.
• What is really charged is in charge_breakdown before the deposit, and in details.charged_amount / details.charged_currency on the deposit. The notification amount / currency carry the same USD figure (for example 5.00 USD, not the equivalent in pesos).
• An exchange-rate spread (fx_spread) is charged only when there is a currency conversion. A USD charge credited to a USD balance carries no spread (fx_spread_amount: 0 in the notification).

Flow

1. Create the deposit with payment_type: "CREDIT_CARD", the brand’s payment_method, your customer’s data and their real client_ip. For cards, the IP’s location must match country.
2. Redirect your customer to data.details.paying.metadata.redirect_url. In production it looks like https://www.cashela.com/partner-checkout/{token}. Open it as a full page or in a new tab: never in an iframe (iframe: false).
3. Your customer pays on the page: cardholder name, card number, expiry date and CVV, and ticks the authorization checkbox to accept the charge. The page shows the amount to be charged.
4. The page shows the result and sends your customer back to your redirect_url (its domain must be in your approved return URLs).
5. You receive the signed notification with the final status and card: { "network": "visa", "last4": "4242" }.

// Excerpt of the deposit returned by POST /deposit-creation for a card option charged in USD
"details": {
  "invoice_country": "MEX",
  "invoice_currency": "MXN",
  "invoice_amount": 92.18,
  "paying": {
    "method": "Credit Card",
    "code": "international-credit-debit-card-visa",
    "metadata": {
      "iframe": false,
      "redirect_url": "https://www.cashela.com/partner-checkout/<token>",
      "validity_period": "2026-10-20T16:05:00+00:00"
    }
  },
  "charged_amount": 5,
  "charged_currency": "USD"
}

Session expiry and declined cards

• The payment link is valid until validity_period (about one hour). After it, the deposit ends CANCELLED and nothing is charged. Your notification arrives with status: "CANCELLED".
• If a card is declined, the page tells your customer and lets them try a different card. The deposit stays PROCESSING while your customer can still retry, until it is paid (COMPLETED) or the session expires (CANCELLED). The number of attempts is limited.
• A declined attempt does not charge the card and does not credit you.

Tip

Do not create a new deposit when your customer comes back after a declined card: the same link stays usable until it expires.

Card data you receive

The deposit and the notification only carry card.network (visa, mastercard, amex, discover, or null when unknown) and card.last4. Never a full card number, CVV, expiry date or token. card is null for non-card methods and before the charge.

Voids and refunds

Card deposits can be voided or refunded through the API. See Voids and refunds.

Testing

In sandbox, drive card deposits to their final status with simulate. Make sure your client_ip and payer data are consistent with the deposit’s country before going live.