Skip to main content
A checkout represents a single payment session for a customer. You create a checkout from your server, receive a checkout_url, and redirect the customer there. The customer selects a payment method, reviews a quote, and submits payment — without any additional work on your end.

​
Create a checkout

curl -X POST https://api.syncgrampay.com/api/v1/payments/checkouts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pricing": {
      "base_currency": "USD",
      "amount": "50.00"
    },
    "customer_email": "customer@example.com",
    "customer_first_name": "Jane",
    "customer_last_name": "Doe",
    "success_url": "https://yourcompany.com/success",
    "cancel_url": "https://yourcompany.com/cancel",
    "metadata": {
      "order_id": "ord_12345"
    },
    "expires_in_minutes": 60
  }'
Endpoint: POST /api/v1/payments/checkouts
Authentication: API key (Bearer token)

​
Request body

​
Pricing

​
pricing
object
required
Pricing configuration for the checkout.

​
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.

​
Redirect URLs

​
success_url
string
URL to redirect the customer after a successful payment. Must use http:// or https://. Maximum 2048 characters. Syncgram appends checkout_id as a query parameter.
​
cancel_url
string
URL to redirect the customer if they cancel. Must use http:// or https://. Maximum 2048 characters.

​
Other fields

​
metadata
object
Key-value pairs to attach to the checkout. Maximum 10 KB total, maximum 20 keys. Values may be strings, numbers, booleans, nested objects, or arrays. Useful for storing order IDs or internal references.
​
reference
string
Your own reference for this checkout. Must be unique within your organization. Maximum 128 characters. If omitted, Syncgram auto-generates one.
​
expires_in_minutes
integer
default:"60"
How long the checkout remains open, in minutes. Range: 1–1440 (up to 24 hours).
​
simulated_outcome
string
Test mode only. Forces a specific final charge status. Accepted values: success, failed, underpaid. Rejected on live mode keys.

​
Response

{
  "checkout_id": "chk_01j9abc123",
  "organization_id": "org_01j9xyz789",
  "checkout_url": "https://pay.syncgrampay.com/c/eyJhbGciOiJIUzI1NiJ9...",
  "status": "OPEN",
  "expires_at": "2025-01-15T11:00:00Z",
  "created_at": "2025-01-15T10:00:00Z"
}
​
checkout_id
string
Unique identifier for the checkout. Use this to look up associated charges.
​
checkout_url
string
Hosted checkout URL containing a signed token. Redirect your customer here. The token is time-bound and matches expires_at.
​
status
string
Current checkout status. Starts as OPEN. Transitions to COMPLETED when the customer submits payment, then to EXPIRED or CANCELLED if applicable.
​
expires_at
string
ISO 8601 datetime when the checkout URL expires.
​
created_at
string
ISO 8601 datetime when the checkout was created.

​
Pricing examples

​
Global USD pricing

The customer sees all payment methods and currencies your organization supports. Exchange rates are computed live. 
{
  "pricing": {
    "base_currency": "USD",
    "amount": "50.00"
  },
  "customer_email": "customer@example.com",
  "customer_first_name": "Jane",
  "customer_last_name": "Doe",
  "success_url": "https://yourcompany.com/success",
  "cancel_url": "https://yourcompany.com/cancel"
}

​
USD with local currency overrides

Fix the amount customers in specific countries pay by providing explicit local prices. Customers in NGN see 75,000 NGN; customers in GHS see 620 GHS. All other currencies fall back to live rate conversion from the USD base. 
{
  "pricing": {
    "base_currency": "USD",
    "amount": "50.00",
    "local_pricing": {
      "NGN": "75000.00",
      "GHS": "620.00"
    }
  },
  "customer_email": "customer@example.com",
  "customer_first_name": "Jane",
  "customer_last_name": "Doe",
  "success_url": "https://yourcompany.com/success",
  "cancel_url": "https://yourcompany.com/cancel"
}

​
Single currency

Restrict the checkout to one specific currency. The customer cannot choose a different currency or payment method that uses a different currency. 
{
  "pricing": {
    "base_currency": "NGN",
    "amount": "75000.00"
  },
  "customer_email": "customer@example.com",
  "customer_first_name": "Jane",
  "customer_last_name": "Doe",
  "success_url": "https://yourcompany.com/success",
  "cancel_url": "https://yourcompany.com/cancel"
}

​
Checkout flow

After the customer opens the checkout_url, the Syncgram-hosted checkout drives them through the following steps. You do not need to implement any of this — it is documented here so you understand what happens between redirect and webhook.
1

Load checkout

The hosted checkout calls GET /api/v1/public/checkouts/{token} to retrieve the initial step and available payment options.
2

Select payment method and currency

The customer picks a currency and payment method from options the backend provides. The checkout submits the selection via POST /api/v1/public/checkouts/{token}/next.
3

Provide additional requirements

Depending on the payment method, the backend may ask for a payment rail (e.g., MTN, Airtel), a phone number for mobile money, or a bank account number. The customer fills in these fields and submits them.
4

Review quote

The checkout fetches a quote from POST /api/v1/public/checkouts/{token}/get-quote, showing the exact amount the customer will pay including fees and the exchange rate.
5

Complete checkout

The customer confirms and the checkout calls POST /api/v1/public/checkouts/{token}/complete, which creates a charge and initiates payment with the payment network.
6

Redirect

After initiating payment, the customer is redirected to your success_url (or cancel_url if they cancel). Syncgram appends ?checkout_id=chk_... to the success URL so you can look up the charge.
The complete response is a payment initiation, not a confirmation. The charge may still be PENDING or PROCESSING when the customer lands on your success page. Use webhooks to confirm when the charge reaches SUCCEEDED.

​
Test mode

Use a test mode API key (sk_test_...) to create checkouts without moving real money. Pass simulated_outcome to control how the charge resolves: 
{
  "pricing": { "base_currency": "USD", "amount": "10.00" },
  "customer_email": "test@example.com",
  "customer_first_name": "Test",
  "customer_last_name": "User",
  "simulated_outcome": "success"
}
Remove simulated_outcome before switching to your live API key.