Get Charge Status

Overview

Retrieve the current status and full details of a payment charge. Use this endpoint to:

Check if a payment has been completed
Get payment provider details and references
View payment amount and currency
See status history and transitions
Retrieve metadata you attached during checkout

A charge represents a customer’s payment attempt. Each completed checkout creates a charge. When to use: Read a charge after a webhook has told you it changed, or when you are reconciling your own records against ours. Do not call it on a timer to watch for a change.

Do not poll this endpoint in a loop. Subscribe to webhook events instead. Webhooks tell you the moment a charge changes, so you learn about it sooner than any polling interval would, and you make one request instead of hundreds.Polling spends your rate limit on every request, whether or not anything changed, and a charge waiting on a customer can stay unchanged for a long time.

Authentication

Type: API Key (required)

Required Headers

Header	Required	Description
`Authorization`	Yes	Format: `Bearer sk_sandbox_...` or `Bearer sk_live_...`

Request

Method & Path

GET /v1/payments/charges/{charge_id}

Path Parameters

View path parameters

string

required

The unique charge identifier (starts with ch_)

Example Request

curl https://api.bachs.io/v1/payments/charges/ch_1a2b3c4d5e6f \
  -H "Authorization: Bearer sk_live_abc123xyz..."

Response

200 Success

Returns complete charge details including status history.

{
  "charge_id": "ch_1a2b3c4d5e6f",
  "organization_id": "acct_7KpQ2mNv4XbR9dLc",
  "customer_id": "cust_xyz789",
  "amount": "75000.00",
  "amount_paid": "75000.00",
  "amount_remaining": "0.00",
  "currency": "NGN",
  "settlement_currency": "NGN",
  "settlement_amount": "74250.00",
  "status": "succeeded",
  "metadata": {
    "order_id": "ORD-12345",
    "product_sku": "PREMIUM-ANNUAL"
  },
  "status_history": [
    {
      "status": "created",
      "occurred_at": "2026-01-24T14:30:00.000Z",
      "reason": null
    },
    {
      "status": "processing",
      "occurred_at": "2026-01-24T14:30:30.000Z",
      "reason": null
    },
    {
      "status": "succeeded",
      "occurred_at": "2026-01-24T14:35:00.000Z",
      "reason": "Payment received and confirmed"
    }
  ],
  "created_at": "2026-01-24T14:30:00.000Z",
  "updated_at": "2026-01-24T14:35:00.000Z"
}

Response Fields

View response fields

string

Unique charge identifier

string

Your organization ID

string

Customer identifier

string

Amount customer paid

string

Currency customer paid in

string

Currency you’ll receive settlement in

string

Amount you’ll receive (after fees)

string

Amount the customer has paid so far (relevant for underpaid charges)

string

Remaining balance (non-zero for underpaid charges)

string

Current charge status (see statuses below)

object

Your custom metadata from checkout

array

Chronological history of status changes

string

ISO 8601 timestamp of charge creation

string

ISO 8601 timestamp of last update

Charge Statuses

Charges go through various statuses during their lifecycle:

Status	Description	Is Final?
`created`	Charge created, awaiting customer action	No
`processing`	Payment initiated, waiting for confirmation	No
`succeeded`	Payment successful, funds settled	Yes
`accepted`	Payment accepted (confirmation may still be pending)	Yes
`failed`	Payment failed or was declined	Yes
`cancelled`	Customer cancelled the payment	Yes
`expired`	Charge expired before payment completed	Yes
`refunded`	Payment was fully refunded	Yes
`partially_refunded`	Payment was partially refunded	Yes
`auto_refunded`	We automatically refunded the payment in full	Yes
`underpaid`	Customer paid less than the required amount	No
`overpaid`	Customer paid more than the required amount	No

Final Statuses

Once a charge reaches a final status (succeeded, accepted, failed, cancelled, expired, refunded, partially_refunded, auto_refunded), it will not change again.

Automatic refunds

auto_refunded means we refunded the full payment automatically. This happens when a refund is required outside your control, such as an early fraud or dispute warning.

Error Responses

404 Not Found

Charge doesn’t exist or doesn’t belong to your organization.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Charge not found"
  }
}

Causes:

Invalid charge_id
Charge belongs to a different organization
Charge exists in a different environment (test vs live)

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

403 Forbidden

You don’t have access to this charge.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Charge does not belong to your organization"
  }
}

Cause: The charge was created by a different organization.

Example Use Case

Scenario: Your order management system fulfils an order as soon as its payment succeeds. Subscribe to the charge events and act when one arrives. You do not ask us for the status. We tell you.

// POST /webhooks/bachs  (verify the signature first, see the webhooks guide)
app.post("/webhooks/bachs", async (req, res) => {
  const event = req.body;

  // Acknowledge straight away, then do the work. A slow reply looks like a
  // failure, and the event gets retried.
  res.sendStatus(200);

  switch (event.type) {
    case "collection.succeeded":
      await fulfilOrder(event.data.metadata.order_id, event.data);
      break;
    case "collection.underpaid":
      // Less than the amount due arrived. Decide whether to accept it, ask for
      // the balance, or refund it. Do not fulfil the order here.
      await handlePartialPayment(event.data.metadata.order_id, event.data);
      break;
    case "collection.failed":
    case "checkout.expired":
      await notifyCustomer(event.data.metadata.order_id, event.data.status);
      break;
  }
});

The events above are collection.succeeded, collection.underpaid, collection.failed and checkout.expired. Subscribe only to the ones you act on. Webhook Events lists every event we send. Handle the same event arriving twice. We retry delivery, and a retry can land after you have already processed the first copy. Key your fulfilment on charge_id so a repeat is ignored.

Recovering a missed event

A webhook can fail to reach you if your endpoint is down. Recover with a scheduled sweep, not a loop for each payment. Once every few minutes, list the charges you still believe are unfinished and read their current status in one request:

curl "https://sandbox-api.bachs.io/v1/payments?status_filter=processing&limit=100" \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..."

One request covers every pending charge you have. A loop for each payment makes one request per payment, per interval, and reaches the same answer more slowly.

A charge still created or processing after 15 minutes is unusual. Read Charge Statuses above, then contact support rather than continuing to retry.

Understanding Settlement Amounts

The settlement_amount is what you actually receive after fees are deducted:

settlement_amount = amount - fees

Example:

Customer pays: NGN 75,000.00 (amount)
Fees: NGN 750.00
You receive: NGN 74,250.00 (settlement_amount)

The fees are calculated based on:

Payment method used
Your fee configuration
Charge amount

Using Status History

The status_history array shows every status change with timestamps:

// Find when payment was completed
const charge = await getCharge("ch_1a2b3c4d5e6f");
const completedEvent = charge.status_history.find(
  (e) => e.status === "succeeded",
);

if (completedEvent) {
  console.log("Payment completed at:", completedEvent.occurred_at);
  console.log(
    "Processing time:",
    new Date(completedEvent.occurred_at) - new Date(charge.created_at),
    "milliseconds",
  );
}

// Check for failures
const failedEvent = charge.status_history.find((e) => e.status === "failed");
if (failedEvent && failedEvent.reason) {
  console.log("Failure reason:", failedEvent.reason);
}

Common Questions

How often should I check a charge?

You should not need to check it at all. Subscribe to webhook events and we notify you the moment the charge changes. If you run a reconciliation sweep to recover missed events, once every few minutes is enough. Most payments finish within 5 to 10 minutes.

What if status is stuck in `created` or `processing`?

Wait at least 10 minutes before assuming an issue
Check if customer completed the payment
Contact support if status doesn’t update after 15 minutes

Can a `succeeded` charge change to `failed`?

No. Once succeeded, the status is final. However, a completed charge can later be refunded.

How do I know the exact amount I’ll receive?

Use the settlement_amount field. This is your net amount after all fees.

Can I get charges for a specific checkout?

Yes, use List Payins and filter by checkout_id.

Create Checkout - Create a checkout that generates a charge
List Payins - List all charges for your organization
Webhook Events - Receive real-time charge updates

Next Steps

After retrieving charge status:

Handle completed payments

If status is succeeded, grant access and update the order.

Handle failed payments

If status is failed, notify the customer and offer retry options.

Handle non-final states

If the status is not final, wait for the webhook. Do not loop on this endpoint.

Enable production webhooks

Set up webhook delivery (see Webhook Documentation).

Get Started

Products & pricing

Subscriptions

Customer portal

Payments

Payouts

Dashboard

Developer Portal

CLI

For You and Your Customers

Get Charge Status

Overview

Authentication

Required Headers

Request

Method & Path

Path Parameters

Example Request

Response

200 Success

Response Fields

Charge Statuses

Final Statuses

Automatic refunds

Error Responses

Example Use Case

Recovering a missed event

Understanding Settlement Amounts

Using Status History

Common Questions

How often should I check a charge?

What if status is stuck in `created` or `processing`?

Can a `succeeded` charge change to `failed`?

How do I know the exact amount I’ll receive?

Can I get charges for a specific checkout?

Next Steps

​Overview

​Authentication

​Required Headers

​Request

​Method & Path

​Path Parameters

​Example Request

​Response

​200 Success

​Response Fields

​Charge Statuses

​Final Statuses

​Automatic refunds

​Error Responses

​Example Use Case

​Recovering a missed event

​Understanding Settlement Amounts

​Using Status History

​Common Questions

​How often should I check a charge?

​What if status is stuck in created or processing?

​Can a succeeded charge change to failed?

​How do I know the exact amount I’ll receive?

​Can I get charges for a specific checkout?

​Related Endpoints

​Next Steps

Overview

Authentication

Required Headers

Request

Method & Path

Path Parameters

Example Request

Response

200 Success

Response Fields

Charge Statuses

Final Statuses

Automatic refunds

Error Responses

Example Use Case

Recovering a missed event

Understanding Settlement Amounts

Using Status History

Common Questions

How often should I check a charge?

What if status is stuck in `created` or `processing`?

Can a `succeeded` charge change to `failed`?

How do I know the exact amount I’ll receive?

Can I get charges for a specific checkout?

Related Endpoints

Next Steps