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

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

    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.

    Tip

    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
        "id": "pay_mbabizu24mvu3mela5njyhpit4",
      3
        "action_id": "act_mbabizu24mvu3mela5njyhpit4",
      4
        "amount": 6540,
      5
        "currency": "USD",
      6
        "approved": true,
      7
        "status": "Authorized",
      8
        "auth_code": "770687",
      9
        "response_code": "10000",
      10
        "response_summary": "Approved",
      11
        "3ds": {
      12
          "downgraded": true,
      13
          "enrolled": "N"
      14
        },
      15
        "risk": {
      16
          "flagged": true
      17
        },
      18
        "source": {
      19
          "type": "card",
      20
          "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
      21
          "billing_address": {
      22
            "address_line1": "123 Anywhere St.",
      23
            "address_line2": "Apt. 456",
      24
            "city": "Anytown",
      25
            "state": "AL",
      26
            "zip": "123456",
      27
            "country": "US"
      28
          },
      29
          "phone": {
      30
            "country_code": "+1",
      31
            "number": "555 123 4567"
      32
          },
      33
          "last4": "4242",
      34
          "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
      35
          "bin": "424242"
      36
        },
      37
        "customer": {
      38
          "id": "cus_udst2tfldj6upmye2reztkmm4i",
      39
          "email": "john.smith@example.com",
      40
          "name": "John Smith"
      41
        },
      42
        "processed_on": "2019-09-10T10:11:12Z",
      43
        "reference": "ORD-5023-4E89",
      44
        "processing": {
      45
          "retrieval_reference_number": "909913440644",
      46
          "acquirer_transaction_id": "440644309099499894406"
      47
        },
      48
        "eci": "06",
      49
        "scheme_id": "489341065491658",
      50
        "links": {
      51
          "self": {
      52
            "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
      53
          },
      54
          "action": {
      55
            "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
      56
          },
      57
          "void": {
      58
            "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
      59
          },
      60
          "capture": {
      61
            "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
      62
          }
      63
        }
      64
      }

      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
              "source": {
        3
                "type": "network_token",
        4
                "token": "4242424242424242",
        5
                "token_type": "vts",
        6
                "expiry_month": "10",
        7
                "expiry_year": "2025",
        8
                "eci": "06",
        9
                "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA"
        10
              },
        11
              "amount": 1000,
        12
              "currency": "USD"
        13
            }

        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.

        Tip

        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
            "id": "pay_mbabizu24mvu3mela5njyhpit4",
          3
            "action_id": "act_mbabizu24mvu3mela5njyhpit4",
          4
            "amount": 6540,
          5
            "currency": "USD",
          6
            "approved": true,
          7
            "status": "Authorized",
          8
            "auth_code": "770687",
          9
            "response_code": "10000",
          10
            "response_summary": "Approved",
          11
            "3ds": {
          12
              "downgraded": true,
          13
              "enrolled": "N"
          14
            },
          15
            "risk": {
          16
              "flagged": true
          17
            },
          18
            "source": {
          19
              "type": "card",
          20
              "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
          21
              "billing_address": {
          22
                "address_line1": "123 Anywhere St.",
          23
                "address_line2": "Apt. 456",
          24
                "city": "Anytown",
          25
                "state": "AL",
          26
                "zip": "123456",
          27
                "country": "US"
          28
              },
          29
              "phone": {
          30
                "country_code": "+1",
          31
                "number": "555 123 4567"
          32
              },
          33
              "last4": "4242",
          34
              "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
          35
              "bin": "424242"
          36
            },
          37
            "customer": {
          38
              "id": "cus_udst2tfldj6upmye2reztkmm4i",
          39
              "email": "john.smith@example.com",
          40
              "name": "John Smith"
          41
            },
          42
            "processed_on": "2019-09-10T10:11:12Z",
          43
            "reference": "ORD-5023-4E89",
          44
            "processing": {
          45
              "retrieval_reference_number": "909913440644",
          46
              "acquirer_transaction_id": "440644309099499894406"
          47
            },
          48
            "eci": "06",
          49
            "scheme_id": "489341065491658",
          50
            "links": {
          51
              "self": {
          52
                "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
          53
              },
          54
              "action": {
          55
                "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
          56
              },
          57
              "void": {
          58
                "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
          59
              },
          60
              "capture": {
          61
                "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
          62
              }
          63
            }
          64
          }

          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

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

            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.

            Tip

            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
                "id": "pay_mbabizu24mvu3mela5njyhpit4",
              3
                "action_id": "act_mbabizu24mvu3mela5njyhpit4",
              4
                "amount": 6540,
              5
                "currency": "USD",
              6
                "approved": true,
              7
                "status": "Authorized",
              8
                "auth_code": "770687",
              9
                "response_code": "10000",
              10
                "response_summary": "Approved",
              11
                "3ds": {
              12
                  "downgraded": true,
              13
                  "enrolled": "N"
              14
                },
              15
                "risk": {
              16
                  "flagged": true
              17
                },
              18
                "source": {
              19
                  "type": "card",
              20
                  "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
              21
                  "billing_address": {
              22
                    "address_line1": "123 Anywhere St.",
              23
                    "address_line2": "Apt. 456",
              24
                    "city": "Anytown",
              25
                    "state": "AL",
              26
                    "zip": "123456",
              27
                    "country": "US"
              28
                  },
              29
                  "phone": {
              30
                    "country_code": "+1",
              31
                    "number": "555 123 4567"
              32
                  },
              33
                  "last4": "4242",
              34
                  "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
              35
                  "bin": "424242"
              36
                },
              37
                "customer": {
              38
                  "id": "cus_udst2tfldj6upmye2reztkmm4i",
              39
                  "email": "john.smith@example.com",
              40
                  "name": "John Smith"
              41
                },
              42
                "processed_on": "2019-09-10T10:11:12Z",
              43
                "reference": "ORD-5023-4E89",
              44
                "processing": {
              45
                  "retrieval_reference_number": "909913440644",
              46
                  "acquirer_transaction_id": "440644309099499894406"
              47
                },
              48
                "eci": "06",
              49
                "scheme_id": "489341065491658",
              50
                "links": {
              51
                  "self": {
              52
                    "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
              53
                  },
              54
                  "action": {
              55
                    "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
              56
                  },
              57
                  "void": {
              58
                    "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
              59
                  },
              60
                  "capture": {
              61
                    "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
              62
                  }
              63
                }
              64
              }

              Using a payment instrument

              You can use a payment instrument to request a payment.

              Request example

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

              Response example

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

              On this page

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