Bango uses cookies to give you the best website experience. By using this website you agree to let Bango use cookies. More info
OK
Bango Developer
  1. Bango Payment
  2. Transactions
  3. Capturing a payment

Capturing a payment

Completing a transaction to transfer funds from a user

In the Bango Platform, transactions are two-step: in the first step your store authorizes payment, and in the second step your store captures payment. To capture payment, you complete a transaction by making a PUT request to the Bango Payment API, specifying the transaction ID. Some payment providers require capture to take place only after a purchased item is shipped or delivered: for physical goods, this means there may be significant time between authorization and capture. Note that an authorized payment that has not been captured typically means the user has not been charged.

If supported by a payment provider, you can capture partial payment if you need to. Here, the user pays less than the authorized amount.

After successfully capturing a payment, the transaction is marked as complete. Any further capture requests for the transaction will fail, even if you captured partial payment. In the partial payment case, to capture the rest of the payment you must authorize a new payment.

As part of the API request, you supply:

  • The transaction ID
  • Optionally, a structure representing the item the user is purchasing (required for partial capture only)
  • Optionally, custom transaction data

The API response is a structure that describes the result of the capture request.

Sequence diagrams
Successful capture

The Bango Platform successfully captures payment:

Failed capture

The Bango Platform fails to capture payment:

Skeleton code

function complete_transaction_full_payment (transaction_id) {
    // *Always* use this endpoint prefix for the Bango Payment API.
    const base_url = "https://api.bango.net/v5/";

    // Result value
    let success = false;

    try {
        // PUT UTF-8 JSON to the Bango Payment API and parse the JSON response.
        // In this request we don't include a body parameter,
        // which means we capture the full payment authorized when
        // we created the transaction.
        let response = rest_client_call({
            method: "PUT",
            url: base_url + "transaction/" + transaction_id,
            headers: {
                "Authorization": get_authorization_header(),
            },
        }).from_json();

        // The responseCode tells us the result.
        switch (response.responseCode) {
            // Success: payment is captured
            case "OK":
                success = true;
                break;

            // Failure: unable to capture payment
            case "DECLINED": // Payment provider declined capture
            case "SPEED_LIMIT": // Request too soon after previous payment
            case "USER_BARRED": // User not allowed to use payment method
            case "USER_INSUFFICIENT_CREDIT": // User cannot afford purchase
            case "USER_NOT_ENABLED": // Payment provider not enabled user
            case "USER_SPEND_LIMIT": // User reached limit imposed by provider
            case "USER_SUSPENDED": // User temporarily barred from payment method
                throw "Unable to capture payment";

            // Merchant problems
            // These indicate issues in your code, not the Bango Platform.
            case "BAD_REQUEST":   // Invalid request
            case "UNAUTHORIZED":  // Check your credentials
            case "NOT_FOUND":  // Invalid transaction ID
                throw "Merchant implementation error";

            // Bango Platform issues
            // These likely indicate transient problems.
            // In production code, you might want to try the request again
            // after a delay, ultimately falling back to an error state.
            case "INTERNAL_ERROR":
            case "CONNECT_ERROR":
            case "FAILURE":
            case "SERVICE_UNAVAILABLE":
            case "CONNECT_TIMEOUT":
                throw "Bango Platform unavailable"

            // This might indicate Bango has added a new response code.
            // Check the documentation again.
            default:
                throw "Unrecognized response code";
        }

    } catch (exception) {
        // Production code might want to notify the merchant in some way,
        // and/or log full details of the exception for later analysis,
        // and degrade gracefully for the user.
        output("An error occurred!");
        output(exception);
    }

    // true if payment captured, false if not
    return success;
}
FAQ
Which request parameters should I set?

In the skeleton code above, the transaction ID is specified as a path parameter but no body parameters are included in the request. This means the user is charged the full amount for the purchase (the price specified when the payment was authorized). To support partial capture, you would pass a body parameter that specifies a replacement paymentItems structure where the grossAmount and/or taxAmount is less than the original.

You could also pass a body parameter that defines an externalTransactionId for the transaction.

See Bango Payment / Merchant API reference / API reference overview for detailed information on all request parameters.

What are all the possible API response structures?

All responses contain a responseCode string that indicates the result of the request. Use this code to determine how to react.

See Bango Payment / Merchant API reference / API reference overview for detailed information on all responses.

Copyright © 2000–2023 Bango.net Limited