US Card Payments (PayIn)

This section documents the endpoints for accepting deposits via US-issued credit and debit cards. These endpoints support the full card flow: authorization, capture, void, and direct charge.

---

Overview

• Supports: Visa, Mastercard, Amex (test numbers in sandbox)
• Use cases: E-commerce, instant wallet top-up, card-not-present transactions
• Authentication: Basic Auth (Business Key + Secret)
• All endpoints: POST requests

---

Endpoints

1. Authorize Card

Method: POST URL: /api/v1/pay-in/us-cards/request-authorize

Authentication: Basic Auth

Request Body

Field	Type	Required	Description
external_identifier	string	Yes	Unique reference for idempotency
description	string	No	Description for the transaction
name_on_the_card	string	Yes	Cardholder name
card_number	string	Yes	Card number (test: 4111111111111111)
card_code	string	Yes	CVV/CVC code
expiration_date	string	Yes	Format: YYYY-MM
address	string	Yes	Billing address
state_name	string	Yes	State
city_name	string	Yes	City
postal_code	string	Yes	Postal code
amount_paid	number	Yes	Amount to authorize
fee_on_payer	boolean	No	If true, payer covers fees

Example Request

{
  "external_identifier": "36215463256",
  "description": "Test authorization",
  "name_on_the_card": "John Doe",
  "card_number": "4111111111111111",
  "card_code": "999",
  "expiration_date": "2026-12",
  "address": "14 Main Street",
  "state_name": "Texas",
  "city_name": "Texas City",
  "postal_code": "46226",
  "amount_paid": 150,
  "fee_on_payer": false
}

---

2. Capture Card Authorization

Method: POST URL: /api/v1/pay-in/us-cards/request-capture

Request Body

Field	Type	Required	Description
id	string	Yes	Authorization ID returned from authorize
external_identifier	string	No	Optional reference
reference	string	No	Optional reference

Example Request

{
  "id": "4ce59270-802e-431e-9b69-b14ffd54389a"
}

---

3. Void Card Authorization

Method: POST URL: /api/v1/pay-in/us-cards/request-void

Request Body

Field	Type	Required	Description
id	string	Yes	Authorization ID to void
external_identifier	string	No	Optional reference
reference	string	No	Optional reference

Example Request

{
  "id": "acee3819-f320-4465-97e4-ebcfe496497e"
}

---

4. Charge Credit Card (One-Step)

Method: POST URL: /api/v1/pay-in/us-cards/charge-credit-card

Request Body

Field	Type	Required	Description
external_identifier	string	Yes	Unique reference for idempotency
name_on_the_card	string	Yes	Cardholder name
card_number	string	Yes	Card number
card_code	string	Yes	CVV/CVC code
expiration_date	string	Yes	Format: YYYY-MM
address	string	Yes	Billing address
state_name	string	Yes	State
city_name	string	Yes	City
postal_code	string	Yes	Postal code
amount_paid	number	Yes	Amount to charge

Example Request

{
  "external_identifier": "65236986456",
  "name_on_the_card": "John Doe",
  "card_number": "4111111111111111",
  "card_code": "999",
  "expiration_date": "2026-12",
  "address": "14 Main Street",
  "state_name": "Texas",
  "city_name": "Texas City",
  "postal_code": "46226",
  "amount_paid": 250
}

---

Response & Error Handling

• Standard Cashela error model applies (see global error section)
• All endpoints return JSON with transaction status, reference, and error codes if applicable

---

Notes

• Use sandbox card numbers for testing
• All card data must be PCI DSS compliant
• Idempotency is enforced via external_identifier
• Fees, settlement, and restrictions are described in the global sections

---

Example cURL (Authorize)

curl -X POST "https://api.cashela.com/api/v1/pay-in/us-cards/request-authorize" \
  -H "Authorization: Basic BASE64_ENCODED_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "external_identifier": "36215463256",
    "name_on_the_card": "John Doe",
    "card_number": "4111111111111111",
    "card_code": "999",
    "expiration_date": "2026-12",
    "address": "14 Main Street",
    "state_name": "Texas",
    "city_name": "Texas City",
    "postal_code": "46226",
    "amount_paid": 150
  }'

---

See Also

• Deposit Creation Flow
• Global Error Model
• Idempotency Guidelines