Capturing a payment

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.

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;
}