Skip to main content

Getting started

The CashXChain API is a REST API. All requests use JSON bodies and Authorization: Bearer <token> headers. This guide walks from zero to a working end-to-end payment.

Base URLs​

Sandbox:    https://api.sandbox.cashxchain.com
Production: https://api.cashxchain.com

All route paths are prefixed with /v1. Use sandbox for all development — it mirrors production behaviour with deterministic mock partners and a faucet for adding test funds.

Step 1 — Get an API key​

Contact [email protected] or sign up at cashxchain.com to get sandbox access. Once your account is provisioned, create an API key from the developer dashboard.

Your sandbox API key starts with sk_sandbox_. Store it securely — it is shown only once at creation.

export CXC_API_KEY=sk_sandbox_...

See API keys for key types and scopes.

Step 2 — Verify the key works​

A quick read against transaction history confirms the key is valid:

curl https://api.sandbox.cashxchain.com/v1/transactions \
  -H "Authorization: Bearer $CXC_API_KEY"

A 200 with an empty array means the key works and the account is reachable. A 401 means the key is invalid or revoked.

Step 3 — Create a customer​

Customers represent your end-users or businesses. Idempotent on email:

curl -X POST https://api.sandbox.cashxchain.com/v1/customers \
  -H "Authorization: Bearer $CXC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: customer-acme-001" \
  -d '{
    "email": "[email protected]",
    "business_name": "Acme Corp",
    "country_code": "US"
  }'

Note the id from the response — you will use it as customer_id in payment calls.

Step 4 — Get an FX quote (optional)​

The public FX endpoint requires no authentication:

curl -X POST https://api.sandbox.cashxchain.com/v1/fx/quotes \
  -H "Content-Type: application/json" \
  -d '{
    "from_currency": "EUR",
    "to_currency": "USD",
    "from_amount": "1000.00"
  }'

The response includes rate, to_amount, and expires_at. To lock a rate for execution, use the persisted quote flow (POST /v1/fx/quote → POST /v1/fx/execute).

Step 5 — Send a transfer​

Internal (CashXChain user to CashXChain user)​

curl -X POST https://api.sandbox.cashxchain.com/v1/transfers \
  -H "Authorization: Bearer $CXC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-2026-001" \
  -d '{
    "recipient_email": "[email protected]",
    "amount": "50.00",
    "currency": "USD",
    "note": "INV-2026-001"
  }'

External (bank account)​

curl -X POST https://api.sandbox.cashxchain.com/v1/transfers \
  -H "Authorization: Bearer $CXC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-2026-002" \
  -d '{
    "recipient": {
      "email": "[email protected]",
      "name": "Vendor GmbH",
      "bank": {
        "country": "DE",
        "bank_name": "Deutsche Bank",
        "account_number": "DE89370400440532013000",
        "routing_number": "37040044",
        "currency": "EUR"
      }
    },
    "amount": "1000.00",
    "currency": "EUR",
    "note": "Invoice payment"
  }'

The response includes transfer_id, status, and estimated_arrival.

Transfer status lifecycle:

pending → quoting → executing → completed
                              ↘ failed
                              ↘ rolled_back

Step 6 — Track the transfer​

curl https://api.sandbox.cashxchain.com/v1/transfers/$TRANSFER_ID \
  -H "Authorization: Bearer $CXC_API_KEY"

API conventions​

  • JSON request and response bodies. Always set Content-Type: application/json on write requests.
  • ISO 8601 timestamps in UTC (2026-06-08T12:00:00Z).
  • Decimal strings for amounts ("1000.00" not 1000).
  • ISO 4217 currency codes (USD, EUR, USDC).
  • ISO 3166-1 alpha-2 country codes (US, DE).
  • UUIDs for all resource IDs.
  • Idempotency-Key header required on all write routes. Use a unique string per distinct operation (invoice number, UUID, etc.). Replaying the same key returns the cached response safely.
  • Pagination: limit + offset or cursor (before) on list endpoints. Returns has_more and next_cursor where applicable.

Sandbox routing rules​

In sandbox, payment routing is deterministic:

CurrencyPartner
USD, EUR, GBPMockPartner — instant, always succeeds
USDC, EURCCoinbase CDP on Solana

Internal (email-to-email) transfers always work in sandbox. External (bank) transfers return 400 unless the bank details match a registered sandbox user.

Next steps​