Create order

curl -X POST 'https://api.yativo.com/api/v1/card-checkout/orders' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Idempotency-Key: 3f1c2a1e-8b7d-4c1e-9f0a-6d2b5e7c9a10' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "4f0c1e1a-8d2b-4c7e-9b1a-3e5f6a7b8c9d",
    "amount": "49.99",
    "currency": "USD",
    "description": "Pro plan, 1 month",
    "reference": "INV-10023",
    "customer_email": "ada@example.com",
    "success_url": "https://shop.example.com/thanks",
    "cancel_url": "https://shop.example.com/cart",
    "metadata": { "plan": "pro" }
  }'

{
  "status": "success",
  "status_code": 201,
  "message": "Checkout created",
  "data": {
    "id": "cco_7wq2k9x0m3c8v1b5n6z4l2j8h0g4f6d1",
    "customer_id": "4f0c1e1a-8d2b-4c7e-9b1a-3e5f6a7b8c9d",
    "reference": "INV-10023",
    "description": "Pro plan, 1 month",
    "status": "pending",
    "currency": "USD",
    "amount": "49.99",
    "platform_fee": "2.05",
    "reserve": "0.00",
    "net_amount": "47.94",
    "refunded_amount": "0.00",
    "disputed_amount": "0.00",
    "checkout_url": "<string>",
    "payment_methods": [
      "<string>"
    ],
    "metadata": {
      "plan": "pro"
    },
    "expires_at": "2023-11-07T05:31:56Z",
    "paid_at": "2023-11-07T05:31:56Z",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

POST

card-checkout

orders

curl -X POST 'https://api.yativo.com/api/v1/card-checkout/orders' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Idempotency-Key: 3f1c2a1e-8b7d-4c1e-9f0a-6d2b5e7c9a10' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "4f0c1e1a-8d2b-4c7e-9b1a-3e5f6a7b8c9d",
    "amount": "49.99",
    "currency": "USD",
    "description": "Pro plan, 1 month",
    "reference": "INV-10023",
    "customer_email": "ada@example.com",
    "success_url": "https://shop.example.com/thanks",
    "cancel_url": "https://shop.example.com/cart",
    "metadata": { "plan": "pro" }
  }'

{
  "status": "success",
  "status_code": 201,
  "message": "Checkout created",
  "data": {
    "id": "cco_7wq2k9x0m3c8v1b5n6z4l2j8h0g4f6d1",
    "customer_id": "4f0c1e1a-8d2b-4c7e-9b1a-3e5f6a7b8c9d",
    "reference": "INV-10023",
    "description": "Pro plan, 1 month",
    "status": "pending",
    "currency": "USD",
    "amount": "49.99",
    "platform_fee": "2.05",
    "reserve": "0.00",
    "net_amount": "47.94",
    "refunded_amount": "0.00",
    "disputed_amount": "0.00",
    "checkout_url": "<string>",
    "payment_methods": [
      "<string>"
    ],
    "metadata": {
      "plan": "pro"
    },
    "expires_at": "2023-11-07T05:31:56Z",
    "paid_at": "2023-11-07T05:31:56Z",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

{
  "status": "failed",
  "status_code": 403,
  "message": "<string>",
  "data": {
    "error": "Card checkout is not enabled for your account. Contact support to request access.",
    "code": "card_checkout_not_enabled"
  },
  "error": {
    "code": "invalid_argument",
    "message": "<string>",
    "request_id": "req_5f2c9a1e7b3d4c8a6e0f1b2d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {},
    "retryable": false,
    "retry_after": 123
  }
}

You set the amount; the buyer cannot change it. Redirect them to checkout_url exactly as returned. Only the card_checkout.order.paid webhook means the buyer paid. The checkout link expires after 60 minutes. platform_fee, reserve and net_amount are fixed when the order is created. See Create an order.

curl -X POST 'https://api.yativo.com/api/v1/card-checkout/orders' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Idempotency-Key: 3f1c2a1e-8b7d-4c1e-9f0a-6d2b5e7c9a10' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "4f0c1e1a-8d2b-4c7e-9b1a-3e5f6a7b8c9d",
    "amount": "49.99",
    "currency": "USD",
    "description": "Pro plan, 1 month",
    "reference": "INV-10023",
    "customer_email": "ada@example.com",
    "success_url": "https://shop.example.com/thanks",
    "cancel_url": "https://shop.example.com/cart",
    "metadata": { "plan": "pro" }
  }'

Authorizations

X-Api-Key

string

header

required

Your API key (yativo_pk_...) from Developers → API Keys. Send together with X-Api-Secret.

X-Api-Secret

string

header

required

Your API secret (yativo_sk_...), shown once when the key is created.

Headers

Idempotency-Key

string

required

A unique string per request to ensure idempotent processing.

Body

application/json

customer_id

string

required

The customer that is selling. Its card_checkout endorsement must be approved.

Example:

"4f0c1e1a-8d2b-4c7e-9b1a-3e5f6a7b8c9d"

amount

string

required

Amount to charge, as a decimal string in major units.

Example:

"49.99"

currency

string

required

Required string length: 3

Example:

"USD"

description

string

required

What the buyer is paying for. Shown on the checkout page.

Required string length: 2 - 255

Example:

"Pro plan, 1 month"

reference

string

Your own order ID. Unique per account. Letters, digits and ._:-/.

Maximum string length: 100

Example:

"INV-10023"

customer_email

string<email>

The buyer's email. Prefills the checkout form.

Example:

"ada@example.com"

customer_name

string

The buyer's name. Prefills the checkout form.

Maximum string length: 120

success_url

string<uri>

HTTPS link shown after a successful payment.

Example:

"https://shop.example.com/thanks"

cancel_url

string<uri>

HTTPS Return to seller link on the checkout page.

Example:

"https://shop.example.com/cart"

metadata

object

Up to 20 string values, returned on the order and in webhooks.

Show child attributes

payment_methods

string[]

Limit this checkout to some of the methods from GET /card-checkout/account. Leave it out to offer every enabled method.

Required array length: 1 - 100 elements

Example:

["card", "apple_pay"]

Response

Checkout created

status

string

Example:

"success"

status_code

integer

Example:

201

message

string

Example:

"Checkout created"

data

object

Show child attributes

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

Authorizations

Headers

Body

Response