Skip to main content
Creates a checkout for your customer. The response includes a checkout_url to redirect the customer to, or embed in your payment flow.

​
Request

POST /api/v1/payments/checkouts
Requires API key authentication via the Authorization: Bearer <api_key> header.

​
Pricing

​
pricing.base_currency
string
required
The base settlement currency code (e.g., USD, NGN). Must be a supported settlement currency.
​
pricing.amount
string
required
The base amount as a decimal string (e.g., "50.00"). Minimum 1.00 for USD, 1000 for NGN.
​
pricing.local_pricing
object
Currency-specific price overrides. Only allowed when base_currency is USD. Keys are currency codes, values are decimal amount strings (e.g., { "NGN": "75000.00", "GHS": "620.00" }). Fiat currencies only.

​
Customer

​
customer_email
string
required
Customer’s email address. Maximum 255 characters.
​
customer_first_name
string
required
Customer’s first name. Maximum 255 characters.
​
customer_last_name
string
required
Customer’s last name. Maximum 255 characters.

​
Options

​
success_url
string
URL to redirect the customer to after a successful payment. Must use http:// or https://. Maximum 2048 characters.
​
cancel_url
string
URL to redirect the customer to if they cancel. Must use http:// or https://. Maximum 2048 characters.
​
metadata
object
Arbitrary key-value pairs to attach to the checkout (e.g., order_id, user_id). Maximum 10KB total; maximum 20 keys. Values may be strings, numbers, booleans, or nested objects/arrays.
​
expires_in_minutes
integer
default:"60"
How long the checkout remains open, in minutes. Accepts 1–1440 (up to 24 hours).
​
reference
string
Your own reference for this checkout (e.g., an order ID). Must be unique within your organization. Maximum 128 characters. Auto-generated if not provided.
​
simulated_outcome
string
Test mode only. Force a specific outcome: success, failed, or underpaid.

​
Response

​
checkout_id
string
required
Unique identifier for the checkout session.
​
organization_id
string
required
Your organization ID.
​
checkout_url
string
required
URL to redirect your customer to complete payment.
​
status
string
required
Initial checkout status. Typically pending.
​
expires_at
string
ISO 8601 timestamp when the checkout expires.
​
created_at
string
required
ISO 8601 creation timestamp.
{
  "checkout_id": "co_a1b2c3d4e5f6",
  "organization_id": "org_xyz789",
  "checkout_url": "https://pay.syncgrampay.com/checkout/co_a1b2c3d4e5f6",
  "status": "pending",
  "expires_at": "2024-01-15T11:00:00Z",
  "created_at": "2024-01-15T10:00:00Z"
}

​
Error codes

StatusDescription
400Invalid pricing, unsupported currency, validation failure, or simulated_outcome used outside test mode.
401Invalid or missing API key.

​
Example

curl --request POST \
  --url https://api.syncgrampay.com/api/v1/payments/checkouts \
  --header 'Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0' \
  --header 'Content-Type: application/json' \
  --data '{
    "pricing": {
      "base_currency": "USD",
      "amount": "50.00",
      "local_pricing": {
        "NGN": "75000.00",
        "GHS": "620.00"
      }
    },
    "customer_email": "customer@example.com",
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "success_url": "https://yourapp.com/success",
    "cancel_url": "https://yourapp.com/cancel",
    "metadata": {
      "order_id": "ord_12345"
    },
    "expires_in_minutes": 60
  }'