Fiat API References

The Yativo Fiat API enables you to send and receive money globally, manage virtual accounts, perform currency exchange, verify customer identities, and let your customers sell by card through Card Checkout. All endpoints return JSON responses.

Base URLs

Environment	Base URL
Production	`https://api.yativo.com/api/v1`
Sandbox	`https://smtp.yativo.com/api/v1`

Use the sandbox environment for development and testing. Sandbox transactions do not move real funds.

Authentication

Send your API key and secret on every request. Create them in the dashboard under Developers → API Keys.

X-Api-Key: YOUR_API_KEY
X-Api-Secret: YOUR_API_SECRET

Requests must come from an IP on the key’s whitelist. See Authentication and IP whitelisting.

Login tokens from POST /auth/login (legacy Account ID and App Secret) have been discontinued. Authorization: Bearer tokens don’t work for API requests. Use X-Api-Key and X-Api-Secret.

Idempotency

Send an Idempotency-Key header on every POST, PUT, PATCH and DELETE request, so a retried request isn’t processed twice.

Idempotency-Key: your-unique-key-here

Use a UUID or a deterministic string based on the operation (e.g. payout-{customer_id}-{timestamp}). Keys are scoped to your account. Reusing a key for a completed request within 60 minutes returns 409. Reusing a key with a different body also returns 409. See Idempotency.

Rate limits

Requests are rate-limited per business account: by default 20 writes (POST, PUT, PATCH, DELETE) and 50 reads (GET) a second. Some endpoints have lower limits. See Rate limits. Over the limit, you get 429 Too Many Requests with a Retry-After header. Wait that many seconds, then retry with exponential backoff.

Standard response format

All successful responses follow this structure:

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": { ... }
}

Error codes

Status Code	Meaning
`200`	OK — Request succeeded
`201`	Created — Resource created successfully
`400`	Bad Request — Invalid request parameters
`402`	Payment Required — Your balance can’t cover the amount or fee
`401`	Unauthorized — Missing or invalid API key or secret
`403`	Forbidden — The request isn’t allowed, for example from an IP that isn’t whitelisted
`404`	Not Found — Resource does not exist
`409`	Conflict — Idempotency key reused with a different body, or the same request is still running
`422`	Unprocessable Entity — Validation failed
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error — Something went wrong on our end

Error response format

Every failed response has status: "failed", and the reason in data. Most errors put a message in data.error, and the same text in message. Validation errors list the failing fields in data, and message is Request failed. Every failed response also includes two objects with the same shape for every endpoint:

error_details: the error message, per-field messages and retry hints. Read errors from here so you don’t have to handle each endpoint’s data shape.
error: a short code, the message and a request_id. Quote the request_id when you contact support. Send your own X-Request-Id header to have it used as the request_id, so you can match the error to your logs.

{
  "status": "failed",
  "status_code": 422,
  "message": "Request failed.",
  "data": {
    "customer_email": ["The customer email field is required."]
  },
  "error": {
    "code": "invalid_argument",
    "message": "Request failed.",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The customer email field is required.",
    "http_status": 422,
    "fields": {
      "customer_email": ["The customer email field is required."]
    },
    "retryable": false,
    "retry_after": null
  }
}

error fields:

Field	Description
`code`	Short code from the HTTP status: `invalid_argument` (`400`, `422`), `unauthenticated` (`401`), `permission_denied` (`403`), `not_found` (`404`), `method_not_allowed` (`405`), `rate_limited` (`429`) or `internal_error` (`5xx`)
`message`	Same as the top-level `message`
`request_id`	Your `X-Request-Id` header if you sent one, otherwise an ID starting `req_`

error_details fields:

Field	Description
`code`	Stable error code from the HTTP status: `bad_request`, `unauthenticated`, `payment_required`, `forbidden`, `not_found`, `method_not_allowed`, `conflict`, `validation_error`, `rate_limited`, `server_error`, `upstream_error`, `service_unavailable` or `upstream_timeout`
`message`	A readable description of the error
`http_status`	The HTTP status code
`fields`	Messages per field. When the error isn’t about a field, the message is under `error`
`retryable`	`true` for `409`, `429`, `500`, `502`, `503` and `504`, where the same request may succeed later
`retry_after`	Seconds to wait before retrying, from the `Retry-After` header. `null` when not set

A 5xx response’s message is always generic. It never contains internal details. Successful responses always return HTTP 200. status_code in the body can be 201 or 202, for example when a resource was created or accepted for review.

Card Checkout

Let your customers sell by debit and credit card on a Yativo-hosted checkout page. Request access, verify each selling customer, create orders, and follow them with card_checkout.order.* webhooks. See the Card Checkout guide.

Request access

Enable Card Checkout on your account, then read pricing and balance.

Verify selling customers

Submit each customer’s card_checkout endorsement and send them to onboarding.

Create an order

Set the amount, get a checkout_url, and send the buyer to pay.

Withdrawals

Let a selling customer withdraw cleared funds to a saved destination.

Action	Method & path
Request access	`POST /card-checkout/account/request-access`
Get account	`GET /card-checkout/account`
Submit endorsement	`POST /card-checkout/customers/{customer_id}/endorsement`
Get selling customer	`GET /card-checkout/customers/{customer_id}`
Create onboarding link	`POST /card-checkout/customers/{customer_id}/onboarding`
List supported payout methods	`GET /card-checkout/customers/{customer_id}/supported-payout-methods`
Create payout method	`POST /card-checkout/customers/{customer_id}/payout-methods`
List payout methods	`GET /card-checkout/customers/{customer_id}/payout-methods`
Update payout method	`PATCH /card-checkout/customers/{customer_id}/payout-methods/{method_id}`
Delete payout method	`DELETE /card-checkout/customers/{customer_id}/payout-methods/{method_id}`
Create withdrawal	`POST /card-checkout/customers/{customer_id}/payouts`
List withdrawals	`GET /card-checkout/customers/{customer_id}/payouts`
Get withdrawal	`GET /card-checkout/customers/{customer_id}/payouts/{payout_id}`
Cancel withdrawal	`POST /card-checkout/customers/{customer_id}/payouts/{payout_id}/cancel`
Get verification form	`GET /card-checkout/customers/{customer_id}/verification`
Submit business verification	`POST /card-checkout/customers/{customer_id}/verification`
Answer verification items	`POST /card-checkout/customers/{customer_id}/verification/information`
Create order	`POST /card-checkout/orders`
List orders	`GET /card-checkout/orders`
Get order	`GET /card-checkout/orders/{id}`

KYC platform

Certain KYC submission endpoints are hosted on a separate platform:

Platform	Base URL
KYC API	`https://kyc.yativo.com`
Individual KYC	`https://kyc.yativo.com/individual/{customer_id}`
Business KYB	`https://kyc.yativo.com/business/{customer_id}`

Overview

Customers

Compliance RFIs

KYC / KYB

KYC Lookups

Payments & Transfers

Card Checkout

Deposits

Virtual Accounts

Wallets

Sandbox

Beneficiaries

Transactions

Virtual Cards

Payouts

Currency Swap

IP Whitelist

Corporate Cards

Corporate Card Transactions

Corporate Card Links

Webhooks

Developer

Fiat API References

Base URLs

Authentication

Idempotency

Rate limits

Standard response format

Error codes

Error response format

Card Checkout

Request access

Verify selling customers

Create an order

Withdrawals

KYC platform

​Base URLs

​Authentication

​Idempotency

​Rate limits

​Standard response format

​Error codes

​Error response format

​Card Checkout

Request access

Verify selling customers

Create an order

Withdrawals

​KYC platform

Base URLs

Authentication

Idempotency

Rate limits

Standard response format

Error codes

Error response format

Card Checkout

KYC platform