Skip to content
Payments / Accept payments / Authorize a payment

Authorize a payment

Last updated: 14th July 2022

This document contains a draft guide outlining how you can process various authorization types through the Unified Payments API. The information provided below is subject to change.

The Unified Payments API is able to process a number of different authorization types:

  • Final: indicates to the schemes that the amount being authorized will not change.
  • Estimated: indicates to the schemes that the amount being authorized is an estimate.
  • Incremental: follows an estimated authorization and either increases the authorization amount for the payment or, for Mastercard only, extends the authorization validity period.

Request a final or estimated authorization

When requesting a payment in the Unified Payments API, you can specify whether you want the authorization to be final or estimated using the authorization_type field. If omitted, the authorization will be requested as final.

If the authorization type is estimated, we will automatically disable auto capture for the payment.

Endpoints

For the full API specification, see the API reference.

    post

    https://api.checkout.com/payments

    Request example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    {
      "source": {
        "type": "card",
        "number": "4242424242424242",
        "expiry_month": 12,
        "expiry_year": 2025
      },
      "amount": 100,
      "currency": "USD",
      "reference": "ORD-752-814",
      "authorization_type": "Estimated",
      "processing_channel_id": "mer_q4dbxom5jbgudnjzjpz7j2z6uq",
      "capture": false
    }

    Response example

    Use the approved field to check whether or not the authorization was successful ("approved": true). The balances object provides an overview of the payment’s balances, which helps you determine the amount that can be used for each subsequent action on the payment.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    {
      "id": "pay_tqgk5c6k2nnexagtcuom5ktlua",
      "action_id": "act_tqgk5c6k2nnexagtcuom5ktlua",
      "amount": 100,
      "currency": "USD",
      "approved": true,
      "status": "Authorized",
      "auth_code": "503198",
      "expires_on": "2020-04-05T10:11:12Z",
      "eci": "05",
      "scheme_id": "511129554406717",
      "response_code": "10000",
      "response_summary": "Approved",
      "balances": {
        "total_authorized": 100,
        "total_voided": 0,
        "available_to_void": 100,
        "total_captured": 0,
        "available_to_capture": 100,
        "total_refunded": 0,
        "available_to_refund": 0
      },
      "risk": {
        "flagged": false
      },
      "source": {
        "id": "src_il5ncjpijceulefzbhkm2c3di4",
        "type": "card",
        "expiry_month": 12,
        "expiry_year": 2025,
        "scheme": "Visa",
        "last4": "4242",
        "fingerprint": "71580B426F1D190D29087FF265D8F48DF1AD34EDE41C27CBFF9D23C1A14D1776",
        "bin": "424242",
        "card_type": "Credit",
        "card_category": "Consumer",
        "issuer": "JPMORGAN CHASE BANK NA",
        "issuer_country": "US",
        "product_id": "A",
        "product_type": "Visa Traditional",
        "avs_check": "S",
        "cvv_check": "Y",
        "payouts": true,
        "fast_funds": "d"
      },
      "customer": {
        "id": "cus_sozpnpktte5uzooigxau35uloq"
      },
      "processed_on": "2020-03-16T22:11:24Z",
      "reference": "ORD-752-814",
      "processing": {
        "acquirer_transaction_id": "8367314942",
        "retrieval_reference_number": "162588399162"
      },
      "_links": {
        "self": {
          "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua"
        },
        "actions": {
          "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/actions"
        },
        "authorize": {
          "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/authorizations"
        },
        "capture": {
          "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/captures"
        },
        "void": {
          "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/voids"
        }
      }
    }

    Request an incremental authorization

    If a payment was requested with an estimated authorization, you can increase the authorization amount for that payment by submitting incremental authorizations, or extend the authorization validity period (Mastercard only).

    Use the details below to set up your request.

    Endpoints

    For the full API specification, see the API reference.

      post

      https://api.checkout.com/payments/{id}/authorizations

      Request example

      1
      2
      3
      4
      {
        "amount": 50,
        "reference": "ORD-752-814"
      }

      Response example

      Use the approved field to check whether or not the authorization was successful ("approved": true). The balances object provides an overview of the payment’s balances, which helps you determine the amount that can be used for each subsequent action on the payment.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      {
        "action_id": "act_q4dbxom5jbgudnjzjpz7j2z6uq",
        "amount": 50,
        "currency": "USD",
        "approved": true,
        "status": "Authorized",
        "auth_code": "503198",
        "expires_on": "2020-04-20T10:11:12Z",
        "eci": "05",
        "scheme_id": "511129554406717",
        "response_code": "10000",
        "response_summary": "Approved",
        "balances": {
          "total_authorized": 150,
          "total_voided": 0,
          "available_to_void": 150,
          "total_captured": 0,
          "available_to_capture": 150,
          "total_refunded": 0,
          "available_to_refund": 0,
        },
        "processed_on": "2020-03-16T22:11:24Z",
        "reference": "ORD-752-814",
        "processing": {
          "acquirer_transaction_id": "8367314942",
          "retrieval_reference_number": "162588399162"
        },
        "_links": {
          "self": {
            "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua"
          },
          "actions": {
            "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/actions"
          },
          "authorize": {
            "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/authorizations"
          },
          "capture": {
            "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/captures"
          },
          "void": {
            "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/voids"
          }
        }
      }

      Retrieve a payment's balances

      To retrieve the balances of a payment, you can use the following endpoint.

      Use the details below to set up your request.

      Endpoints

      For the full API specification, see the API reference.

        get

        https://api.checkout.com/payments/{id}

        Response example

        In the response, you will be provided with the details of your payment. This includes a balances object containing the following fields:

        Field nameDescription

        total_authorized

        The total amount that has been authorized.

        total_voided

        The total amount that has been voided.

        available_to_void

        The total amount that is still available for voiding.

        total_captured

        The total amount that has been captured.

        available_to_capture

        The total amount that is still available for capture.

        total_refunded

        The total amount that has been refunded.

        available_to_refund

        The total amount that is still available for refund.

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        28
        29
        30
        31
        32
        33
        34
        35
        36
        37
        38
        39
        40
        41
        42
        43
        44
        45
        46
        47
        48
        49
        50
        51
        52
        53
        54
        55
        56
        57
        58
        59
        60
        61
        62
        {
          "id": "pay_4gbjiuwysylutbdnxboxiebifq",
          "requested_on": "2020-03-17T16:06:51Z",
          "source": {
            "id": "src_sp7e7ehmsqlevaqkzso2ajilue",
            "type": "card",
            "expiry_month": 12,
            "expiry_year": 2025,
            "scheme": "Visa",
            "last4": "4242",
            "fingerprint": "71580B426F1D190D29087FF265D8F48DF1AD34EDE41C27CBFF9D23C1A14D1776",
            "bin": "424242",
            "card_type": "Credit",
            "card_category": "Consumer",
            "issuer": "JPMORGAN CHASE BANK NA",
            "issuer_country": "US",
            "product_id": "A",
            "product_type": "Visa Traditional",
            "avs_check": "S",
            "cvv_check": "Y",
            "payouts": true,
            "fast_funds": "d"
          },
          "amount": 150,
          "currency": "USD",
          "payment_type": "Regular",
          "reference": "ORD-752-814",
          "status": "Captured",
          "approved": true,
          "risk": {
            "flagged": false
          },
          "customer": {
            "id": "cus_gp6e4vr7q4bufi4tcbn7oni65u"
          },
          "billing_descriptor": {
            "name": "Fiona's Fashion",
            "city": "New York"
          },
          "balances": {
            "total_authorized": 150,
            "total_voided": 0,
            "available_to_void": 0,
            "total_captured": 150,
            "available_to_capture": 0,
            "total_refunded": 0,
            "available_to_refund": 150
          },
          "eci": "05",
          "scheme_id": "961268269566117",
          "_links": {
            "self": {
              "href": "https://api.sandbox.checkout.com/payments/pay_4gbjiuwysylutbdnxboxiebifq"
            },
            "actions": {
              "href": "https://api.sandbox.checkout.com/payments/pay_4gbjiuwysylutbdnxboxiebifq/actions"
            },
            "refund": {
              "href": "https://api.sandbox.checkout.com/payments/pay_4gbjiuwysylutbdnxboxiebifq/refunds"
            }
          }
        }

        On this page

        Request a final or estimated authorization
        Request an incremental authorization
        Retrieve a payment's balances