Skip to content

Request a payment

Last updated: April 29, 2022

There are four possible ways for you to request a payment:


Using a token

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

    Copied!

    IPv4 or IPv6 addresses?

    The optional payment_ip field, which is used by our risk engine to check the customer's IP address, only accepts IPv4 addresses.

    Request example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    {
    "source": {
    "type": "token",
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
    },
    "amount": 6500,
    "currency": "USD",
    "processing_channel_id": "pc_ovo75iz4hdyudnx6tu74mum3fq",
    "reference": "ORD-5023-4E89",
    "metadata": {
    "udf1": "TEST123",
    "coupon_code": "NY2018",
    "partner_id": 123989
    }
    }

    Response example

    Use the approved field to check whether or not the authorization was successful ("approved": true). If your authorization was not successful, it's possible the payment used an invalid/expired card, or a valid card with an insufficient available balance.

    If you received a 202 response, the payment requires a redirect. For example, if the payment is 3D Secure.

    The following pages can help you understand the response message:

    The possible values for the status field in the synchronous 201 response are Authorized, Pending, Card Verified, or Declined. Note that Pending only applies to 3D Secure payments. You can use Workflows or the Get payment details endpoint for asynchronous status updates.

      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
      {
      "id": "pay_mbabizu24mvu3mela5njyhpit4",
      "action_id": "act_mbabizu24mvu3mela5njyhpit4",
      "amount": 6540,
      "currency": "USD",
      "approved": true,
      "status": "Authorized",
      "auth_code": "770687",
      "response_code": "10000",
      "response_summary": "Approved",
      "3ds": {
      "downgraded": true,
      "enrolled": "N"
      },
      "risk": {
      "flagged": true
      },
      "source": {
      "type": "card",
      "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
      "billing_address": {
      "address_line1": "Checkout.com",
      "address_line2": "90 Tottenham Court Road",
      "city": "London",
      "state": "London",
      "zip": "W1T 4TJ",
      "country": "GB"
      },
      "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
      },
      "last4": "4242",
      "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
      "bin": "424242"
      },
      "customer": {
      "id": "cus_udst2tfldj6upmye2reztkmm4i",
      "email": "brucewayne@gmail.com",
      "name": "Bruce Wayne"
      },
      "processed_on": "2019-09-10T10:11:12Z",
      "reference": "ORD-5023-4E89",
      "processing": {
      "retrieval_reference_number": "909913440644",
      "acquirer_transaction_id": "440644309099499894406"
      },
      "eci": "06",
      "scheme_id": "489341065491658",
      "links": {
      "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
      },
      "action": {
      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
      },
      "void": {
      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
      },
      "capture": {
      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
      }
      }
      }

      Using a network token

      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

        Copied!

        IPv4 or IPv6 addresses?

        The optional payment_ip field, which is used by our risk engine to check the customer's IP address, only accepts IPv4 addresses.

        Request example

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        {
        "source": {
        "type": "network_token",
        "token": "4242424242424242",
        "token_type": "vts",
        "expiry_month": "10",
        "expiry_year": "2025",
        "eci": "06",
        "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA"
        },
        "amount": 1000,
        "currency": "USD"
        }

        Response example

        Use the approved field to check whether or not the authorization was successful ("approved": true). If your authorization was not successful, it's possible the payment used an invalid/expired card, or a valid card with an insufficient available balance.

        If you received a 202 response, the payment requires a redirect. For example, if the payment is 3D Secure.

        The following pages can help you understand the response message:

        The possible values for the status field include Authorized, Pending, Card Verified, Captured, Declined, or Paid. Note that Pending only applies to 3D Secure payments.

          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
          {
          "id": "pay_mbabizu24mvu3mela5njyhpit4",
          "action_id": "act_mbabizu24mvu3mela5njyhpit4",
          "amount": 6540,
          "currency": "USD",
          "approved": true,
          "status": "Authorized",
          "auth_code": "770687",
          "response_code": "10000",
          "response_summary": "Approved",
          "3ds": {
          "downgraded": true,
          "enrolled": "N"
          },
          "risk": {
          "flagged": true
          },
          "source": {
          "type": "card",
          "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
          "billing_address": {
          "address_line1": "Checkout.com",
          "address_line2": "90 Tottenham Court Road",
          "city": "London",
          "state": "London",
          "zip": "W1T 4TJ",
          "country": "GB"
          },
          "phone": {
          "country_code": "+1",
          "number": "415 555 2671"
          },
          "last4": "4242",
          "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
          "bin": "424242"
          },
          "customer": {
          "id": "cus_udst2tfldj6upmye2reztkmm4i",
          "email": "brucewayne@gmail.com",
          "name": "Bruce Wayne"
          },
          "processed_on": "2019-09-10T10:11:12Z",
          "reference": "ORD-5023-4E89",
          "processing": {
          "retrieval_reference_number": "909913440644",
          "acquirer_transaction_id": "440644309099499894406"
          },
          "eci": "06",
          "scheme_id": "489341065491658",
          "links": {
          "self": {
          "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
          },
          "action": {
          "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
          },
          "void": {
          "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
          },
          "capture": {
          "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
          }
          }
          }

          Using full card details

          If you are SAQ D PCI compliant, you can use our Full Card API to request a payment using the full card details. To enable full card processing on your account, contact your Solution Engineer or support@checkout.com.

          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

            Copied!

            IPv4 or IPv6 addresses?

            The optional payment_ip field, which is used by our risk engine to check the customer's IP address, only accepts IPv4 addresses.

            Request example

            1
            2
            3
            4
            5
            6
            7
            8
            9
            10
            11
            12
            13
            14
            15
            16
            17
            {
            "source": {
            "type": "card",
            "number": "4242424242424242",
            "expiry_month": 12,
            "expiry_year": 2022
            },
            "amount": 6500,
            "currency": "USD",
            "processing_channel_id": "processing_channel_id",
            "reference": "ORD-5023-4E89",
            "metadata": {
            "udf1": "TEST123",
            "coupon_code": "NY2018",
            "partner_id": 123989
            }
            }

            Response example

            Use the approved field to check whether or not the authorization was successful ("approved": true). If your authorization was not successful, it's possible the payment used an invalid/expired card, or a valid card with an insufficient available balance.

            If you received a 202 response, the payment requires a redirect. For example, if the payment is 3D Secure.

            The following pages can help you understand the response message:

            The possible values for the status field include Authorized, Pending, Card Verified, Captured, Declined, or Paid. Note that Pending only applies to 3D Secure payments.

              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
              {
              "id": "pay_mbabizu24mvu3mela5njyhpit4",
              "action_id": "act_mbabizu24mvu3mela5njyhpit4",
              "amount": 6540,
              "currency": "USD",
              "approved": true,
              "status": "Authorized",
              "auth_code": "770687",
              "response_code": "10000",
              "response_summary": "Approved",
              "3ds": {
              "downgraded": true,
              "enrolled": "N"
              },
              "risk": {
              "flagged": true
              },
              "source": {
              "type": "card",
              "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
              "billing_address": {
              "address_line1": "Checkout.com",
              "address_line2": "90 Tottenham Court Road",
              "city": "London",
              "state": "London",
              "zip": "W1T 4TJ",
              "country": "GB"
              },
              "phone": {
              "country_code": "+1",
              "number": "415 555 2671"
              },
              "last4": "4242",
              "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
              "bin": "424242"
              },
              "customer": {
              "id": "cus_udst2tfldj6upmye2reztkmm4i",
              "email": "brucewayne@gmail.com",
              "name": "Bruce Wayne"
              },
              "processed_on": "2019-09-10T10:11:12Z",
              "reference": "ORD-5023-4E89",
              "processing": {
              "retrieval_reference_number": "909913440644",
              "acquirer_transaction_id": "440644309099499894406"
              },
              "eci": "06",
              "scheme_id": "489341065491658",
              "links": {
              "self": {
              "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
              },
              "action": {
              "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
              },
              "void": {
              "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
              },
              "capture": {
              "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
              }
              }
              }

              Using a payment instrument

              You can use a payment instrument to request a payment.

              Request example

              1
              2
              3
              4
              5
              6
              7
              8
              9
              {
              "source": {
              "type": "id",
              "id": "src_wmlfc3zyhqzehihu7giusaaawu"
              },
              "amount": 6500,
              "currency": "USD",
              "reference": "ORD-5023-4E89"
              }

              Response example

              1
              2
              3
              4
              5
              6
              7
              8
              9
              10
              11
              12
              13
              14
              {
              "id": "pay_mbabizu24mvu3mela5njyhpit4",
              "amount": 6500,
              "currency": "USD",
              "approved": true,
              "status": "Authorized",
              "auth_code": "770687",
              "response_code": "10000",
              "response_summary": "Approved",
              "source": {
              "type": "id",
              "id": "src_wmlfc3zyhqzehihu7giusaaawu"
              }
              }