Skip to content
Payments / Accept payments / Request a payment

Request a payment

Last updated: 14th July 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

    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

        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.

          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

            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 also convert a card token into a payment instrument using the /instruments endpoint.

              For the full API specification, see the API reference.

              Using this flow will not check the card is valid before storing it.

              Endpoints

                post

                https://api.checkout.com/instruments

                Request example

                In this example, a new customer email and name is provided. This will create a new customer and the payment instrument will automatically become this customer's default instrument.

                1
                2
                3
                4
                5
                6
                7
                8
                9
                10
                11
                12
                13
                14
                15
                16
                17
                18
                19
                20
                21
                22
                {
                  "type": "token",
                  "token": "tok_asoto22g2fsu7prwomy12sgfsa",
                  "account_holder": {
                    "billing_address": {
                      "address_line1": "Checkout.com",
                      "address_line2": "90 Tottenham Court Road",
                      "city": "London",
                      "state": "London",
                      "zip": "W1T 4TJ",
                      "country": "GB"
                    },
                    "phone": {
                      "country_code": "975",
                      "number": "174217187"
                    }
                  },
                  "customer": {
                    "email": "JohnTest@test.com",
                    "name": "John Test"
                  }
                }

                Response example

                If the request was successful, you will receive a 201 success response. This will include the newly created payment instrument id (prefixed with src_).

                It will also include the details of the customer to which the new instrument has been linked.

                  1
                  2
                  3
                  4
                  5
                  6
                  7
                  8
                  9
                  10
                  11
                  12
                  13
                  14
                  15
                  16
                  17
                  18
                  19
                  20
                  21
                  {
                    "id": "src_wmlfc3zyhqzehihu7giusaaawu",
                    "type": "card",
                    "fingerprint": "string",
                    "expiry_month": 6,
                    "expiry_year": 2025,
                    "scheme": "VISA",
                    "last4": "9996",
                    "bin": "454347",
                    "card_type": "Credit",
                    "card_category": "Consumer",
                    "issuer": "GOTHAM STATE BANK",
                    "issuer_country": "US",
                    "product_id": "F",
                    "product_type": "CLASSIC",
                    "customer": {
                      "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
                      "email": "JohnTest@test.com",
                      "name": "John Test"
                    }
                  }

                  You can then use the ID returned in the response in future payment requests.

                  Request example

                  1
                  2
                  3
                  4
                  5
                  6
                  7
                  8
                  {
                    "source": {
                      "type": "id",
                        "id": "src_wmlfc3zyhqzehihu7giusaaawu",
                    },
                    "amount": 6500,
                    "currency": "USD"
                  }

                  On this page

                  Using a token
                  Using a network token
                  Using full card details
                  Using a payment instrument