Skip to main content
A charge is created automatically when a customer initiates payment on a checkout. You do not create charges directly. Use the charges API to retrieve status, inspect payment history, and handle underpaid charges.

​
Get a charge

Retrieve the full status and metadata for a single charge by its ID. 
curl https://api.syncgrampay.com/api/v1/payments/charges/chr_01j9abc123 \
  -H "Authorization: Bearer sk_live_..."
Endpoint: GET /api/v1/payments/charges/{charge_id}
Authentication: API key

​
Response

{
  "charge_id": "chr_01j9abc123",
  "organization_id": "org_01j9xyz789",
  "customer_id": "cus_01j9def456",
  "amount": "50.00",
  "currency": "NGN",
  "settlement_currency": "USD",
  "settlement_amount": "50.00",
  "status": "SUCCEEDED",
  "metadata": {
    "order_id": "ord_12345"
  },
  "status_history": [
    {
      "status": "PENDING",
      "occurred_at": "2025-01-15T10:00:00Z",
      "provider_reference": null,
      "reason": null
    },
    {
      "status": "PROCESSING",
      "occurred_at": "2025-01-15T10:03:21Z",
      "provider_reference": "prov_ref_abc",
      "reason": null
    },
    {
      "status": "SUCCEEDED",
      "occurred_at": "2025-01-15T10:05:44Z",
      "provider_reference": "prov_ref_abc",
      "reason": null
    }
  ],
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:05:44Z"
}
​
charge_id
string
Unique identifier for the charge.
​
amount
string
The amount the customer was asked to pay, as a decimal string in currency.
​
currency
string
The currency the customer paid in (e.g., NGN, GHS, USDT_TRC20).
​
settlement_currency
string
The currency Syncgram credits to your balance (e.g., USD, NGN).
​
settlement_amount
string
The amount credited to your balance in settlement_currency.
​
status
string
Current charge status. See Charge statuses.
​
metadata
object
Key-value metadata you attached to the checkout that originated this charge.
​
status_history
array
Ordered list of status transitions, earliest first. Each entry includes status, occurred_at, provider_reference, and reason.

​
List charges (payins)

Retrieve a paginated list of all charges for your organization. 
curl "https://api.syncgrampay.com/api/v1/payments/payins?limit=20&offset=0" \
  -H "Authorization: Bearer sk_live_..."
Endpoint: GET /api/v1/payments/payins
Authentication: API key

​
Query parameters

​
limit
integer
default:"50"
Number of charges to return. Range: 1–100.
​
offset
integer
default:"0"
Number of charges to skip. Use with limit for pagination.
​
status_filter
string
Filter by charge status. Accepted values: PENDING, PROCESSING, SUCCEEDED, ACCEPTED, FAILED, UNDERPAID, EXPIRED.

​
Response

{
  "total": 143,
  "items": [
    {
      "id": "chr_01j9abc123",
      "reference": "ref_ord_12345",
      "status": "SUCCEEDED",
      "is_refundable": true,
      "customer_email": "customer@example.com",
      "customer_name": "Jane Doe",
      "amount": "75000.00",
      "amount_paid": "75000.00",
      "amount_remaining": "0.00",
      "amount_collected": "50.00",
      "currency": "NGN",
      "transaction_date": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T10:05:44Z"
    }
  ]
}

​
Get a single payin

Retrieve full detail for one charge including payment method, channel, and customer info. 
curl https://api.syncgrampay.com/api/v1/payments/payins/chr_01j9abc123 \
  -H "Authorization: Bearer sk_live_..."
Endpoint: GET /api/v1/payments/payins/{charge_id}
Authentication: API key

​
Response fields

​
charge_id
string
Unique identifier for the charge.
​
reference
string
Your reference from the originating checkout, if provided.
​
status
string
Current charge status.
​
is_refundable
boolean
Whether this charge can be refunded. Only true for charges in SUCCEEDED or ACCEPTED status with a supported payment method.
​
amount
string
Amount the customer was asked to pay.
​
amount_paid
string
Amount actually received. May be less than amount for underpaid charges.
​
amount_remaining
string
Difference between amount and amount_paid. Zero for fully paid charges.
​
currency
string
Currency the customer paid in.
​
payment_source_type
string
Payment category: bank_transfer, mobile_money, or crypto.
​
payment_method
string
Payment method identifier (e.g., BANK_TRANSFER, MOBILE_MONEY, CRYPTO).
​
channel
string
Origination channel: api, payment_link, or similar.
​
customer
object
Customer name and email from the originating checkout.
​
created_at
string
ISO 8601 datetime when the charge was created.
​
completed_at
string
ISO 8601 datetime when the charge reached a terminal status. Null if not yet complete.

​
Charge statuses

StatusDescription
PENDINGWaiting for the customer to send payment.
PROCESSINGPayment received; being verified or settled by the payment network.
SUCCEEDEDFull amount confirmed. Funds will be credited to your balance.
ACCEPTEDUnderpaid charge accepted manually. Syncgram settles what was received.
FAILEDPayment failed or was rejected. No funds collected.
UNDERPAIDCustomer sent less than the required amount.
EXPIREDCheckout or charge expired before payment was completed.

​
Underpayment handling

When a customer sends less than the required amount, the charge moves to UNDERPAID. You have two options:
  1. Wait — if your payment method supports it, the customer can top up. Syncgram will update the charge once the full amount arrives.
  2. Accept — settle the charge based on what was received. Use the preview endpoint first to see exactly what will be credited, then confirm.

​
Preview underpayment acceptance

Before accepting, preview what Syncgram will settle. 
curl -X POST https://api.syncgrampay.com/api/v1/payments/payins/underpayments/preview \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"charge_id": "chr_01j9abc123"}'
Endpoint: POST /api/v1/payments/payins/underpayments/preview
Response
{
  "charge_id": "chr_01j9abc123",
  "checkout_reference": "ref_ord_12345",
  "status": "UNDERPAID",
  "currency": "NGN",
  "expected_amount": "75000.00",
  "received_amount": "50000.00",
  "amount_remaining": "25000.00",
  "settlement_currency": "USD",
  "settlement_amount_current": "0.00",
  "settlement_amount_if_accepted": "33.33"
}

​
Confirm underpayment acceptance

If you are satisfied with the preview, confirm to settle. 
curl -X POST https://api.syncgrampay.com/api/v1/payments/payins/underpayments/confirm \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"charge_id": "chr_01j9abc123"}'
Endpoint: POST /api/v1/payments/payins/underpayments/confirm
Response
{
  "charge_id": "chr_01j9abc123",
  "status": "ACCEPTED",
  "currency": "NGN",
  "settlement_currency": "USD",
  "settlement_amount_settled": "33.33"
}
Confirming underpayment acceptance is irreversible. The charge moves to ACCEPTED and Syncgram credits the partial settlement amount to your balance.
Both endpoints return 400 Bad Request if the charge is not in UNDERPAID status.