CHcheckout
Payments

Request a payment or payout

Send a payment or payout.<br><br><b>Note</b>: successful payout requests will always return a 202 response.

post/payments

Request

Headers

Cko-Idempotency-Keystring

An optional idempotency key for safely retrying payment requests

Cko-Encryption-Key-Idstring

The ID of the encryption key to use for encrypting sensitive payment data. See Encrypt sensitive fields in your payment requests for more information.

Cko-Encrypted-Propertiesstring

The field you want to encrypt using the encryption key in Cko-Encryption-Key-Id.

Request body

OR
OR
OR
OR

Example request

{
  "source": {
    "number": "4543474002249996",
    "expiry_month": 6,
    "expiry_year": 2030,
    "name": "Bruce Wayne",
    "cvv": "956",
    "stored": true,
    "billing_address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "account_holder": {
      "type": "individual",
      "first_name": "Toby",
      "last_name": "Arden"
    },
    "type": "card"
  },
  "fallback_source": {
    "number": "4543474002249996",
    "expiry_month": 6,
    "expiry_year": 2030,
    "name": "Bruce Wayne",
    "cvv": "956",
    "stored": true,
    "billing_address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "type": "card"
  },
  "amount": 6540,
  "currency": "USD",
  "payment_type": "Recurring",
  "payment_plan": {
    "amount_variability": "Variable",
    "days_between_payments": 28,
    "total_number_of_payments": 5,
    "current_payment_number": 3,
    "expiry": "20251031",
    "name": "Subscription 1234",
    "start_date": "20260507",
    "amount": 1234
  },
  "reference": "ORD-5023-4E89",
  "description": "Set of 3 masks",
  "authorization_type": "Estimated",
  "partial_authorization": {
    "enabled": true
  },
  "capture": true,
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "email": "brucewayne@gmail.com",
    "name": "Bruce Wayne",
    "tax_number": "1350693505279",
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "summary": {
      "registration_date": "2023-05-01T00:00:00.0000000",
      "first_transaction_date": "2023-07-01T00:00:00.0000000",
      "last_payment_date": "2023-08-01T00:00:00.0000000",
      "total_order_count": 15,
      "last_payment_amount": 500,
      "is_premium_customer": true,
      "is_returning_customer": true,
      "lifetime_value": 500
    }
  },
  "billing_descriptor": {
    "name": "SUPERHEROES.COM",
    "city": "GOTHAM",
    "local_descriptors": [
      {
        "name": "漢字"
      }
    ]
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "from_address_zip": "123456",
    "timeframe": "SameDay",
    "method": "BillingAddress",
    "delay": 5
  },
  "3ds": {
    "enabled": "true",
    "allow_upgrade": true,
    "exemption": "low_value"
  },
  "authentication": {
    "preferred_experiences": [
      "google_spa",
      "3ds"
    ]
  },
  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  "previous_payment_id": "pay_fun26akvvjjerahhctaq2uzhu4",
  "risk": {
    "device_session_id": "dsid_ipsmclhxwq72phhr32iwfvrflm",
    "device": {
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
      "network": {
        "ipv4": "63.33.82.13",
        "ipv6": "2001:0000:130F:0000:0000:09C0:876A:130B"
      },
      "provider": {
        "id": "1728646225211.AfUgxG",
        "name": "List [ \"merchant\", \"fingerprintjs\", \"riskify\" ]"
      },
      "timestamp": "2024-02-06T15:00:00.000Z",
      "timezone": "60",
      "language": "FR-fr",
      "color_depth": "16",
      "screen_height": "1080",
      "screen_width": "1920"
    }
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/fail",
  "payment_ip": "90.197.169.245",
  "sender": {
    "type": "individual",
    "first_name": "John",
    "last_name": "Jones",
    "date_of_birth": "1985-05-15T00:00:00.0000000",
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "identification": {
      "type": "driving_licence",
      "number": "1234",
      "issuing_country": "GT"
    }
  },
  "recipient": {
    "dob": "1985-05-15T00:00:00.0000000",
    "account_number": "5555554444",
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "zip": "SW1A",
    "first_name": "John",
    "last_name": "Jones"
  },
  "amount_allocations": [
    {
      "id": "ent_w4jelhppmfiufdnatam37wrfc4",
      "amount": 1000,
      "reference": "ORD-5023-4E89",
      "commission": {
        "amount": 1000,
        "percentage": 1.125
      }
    }
  ],
  "processing": {
    "order_id": "123456789",
    "tax_amount": 3000,
    "surcharge_amount": 200,
    "shipping_amount": 300,
    "shipping_tax_amount": 100,
    "product_type": "QR Code",
    "open_id": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
    "original_order_amount": 10,
    "receipt_id": "10",
    "terminal_type": "WAP",
    "os_type": "ANDROID",
    "locale": "en-US",
    "airline_data": [
      {
        "ticket": {
          "number": "045-21351455613",
          "issue_date": "2023-05-20T00:00:00.0000000",
          "issuing_carrier_code": "AI",
          "travel_package_indicator": "B",
          "travel_agency_name": "World Tours",
          "travel_agency_code": "01"
        },
        "passenger": [
          {
            "first_name": "John",
            "last_name": "White",
            "date_of_birth": "1990-05-26T00:00:00.0000000",
            "address": {
              "country": "US"
            }
          }
        ],
        "flight_leg_details": [
          {
            "flight_number": "101",
            "carrier_code": "BA",
            "class_of_travelling": "J",
            "departure_airport": "LHR",
            "departure_date": "2023-06-19T00:00:00.0000000",
            "departure_time": "15:30",
            "arrival_airport": "LAX",
            "stop_over_code": "x",
            "fare_basis_code": "SPRSVR"
          }
        ]
      }
    ],
    "accommodation_data": [
      {
        "name": "The Sea View Hotel",
        "booking_reference": "HOTEL123",
        "check_in_date": "2023-06-20T00:00:00.0000000",
        "check_out_date": "2023-06-23T00:00:00.0000000",
        "address": {
          "address_line1": "123 Beach Road",
          "zip": "10001"
        },
        "state": "FL",
        "country": "USA",
        "city": "Los Angeles",
        "number_of_rooms": 2,
        "guests": [
          {
            "first_name": "Jane",
            "last_name": "Doe",
            "date_of_birth": "1985-07-14T00:00:00.0000000"
          }
        ],
        "room": [
          {
            "rate": "70",
            "number_of_nights_at_room_rate": "3"
          }
        ],
        "property_phone": [
          {
            "country_code": "44",
            "number": "7123456789"
          }
        ],
        "customer_service_phone": [
          {
            "country_code": "44",
            "number": "7123456789"
          }
        ]
      }
    ],
    "line_of_business": "Flights",
    "service_type": "standard",
    "partner_code": "902111",
    "provision_network_token": true,
    "affiliate_url": "www.mycrypto.com",
    "purchase_country": "GB",
    "foreign_retailer_amount": 200,
    "reconciliation_id": "4123495123",
    "aggregator": {
      "sub_merchant_id": "9cf70789ba90123",
      "aggregator_id_visa": "10012345",
      "aggregator_id_mc": "00000123456"
    }
  },
  "items": [
    {
      "type": "digital",
      "sub_type": "stablecoin",
      "name": "Necklace",
      "quantity": 2,
      "unit_price": 50,
      "reference": "858818ac",
      "commodity_code": "DEF123",
      "unit_of_measure": "metres",
      "total_amount": 29000,
      "tax_rate": 2000,
      "tax_amount": 1000,
      "discount_amount": 1000,
      "wxpay_goods_id": "1001",
      "service_ends_on": "2025-01-01T00:00:00.0000000",
      "purchase_country": "GB",
      "foreign_retailer_amount": 200
    }
  ],
  "metadata": {
    "coupon_code": "NY2018"
  },
  "segment": {
    "brand": "Acme Corporation",
    "business_category": "Inward Payments",
    "market": "UK"
  }
}

Response

Payment processed successfully

idstring required

The payment identifier.

action_idstring required

The action identifier

amountinteger required

The payment amount.

amount_requestedinteger

The full amount from the original authorization, if a partial authorization was requested and approved.

currencystring required

The three-letter <a href="https://www.checkout.com/docs/resources/codes/currency-codes" target="_blank">ISO currency code</a> of the payment

approvedboolean required

Whether or not the authorization or capture was successful

status'Authorized' | 'Pending' | 'Card Verified' | 'Declined' | 'Retry Scheduled' required

The status of the payment

auth_codestring

The acquirer authorization code if the payment was authorized

response_codestring required

The Gateway response code

response_summarystring

The Gateway response summary

expires_onstring

The timestamp (ISO 8601 code) for when the authorization's validity period expires

processed_onstring date-time required

Read-only UTC timestamp, automatically assigned by us

referencestring

Your reference for the payment

ecistring

The final Electronic Commerce Indicator (ECI) security level used to authorize the payment. Applicable for 3D Secure and network token payments

scheme_idstring

The scheme transaction identifier

Example response

{
  "id": "pay_mbabizu24mvu3mela5njyhpit4",
  "action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
  "amount": 6540,
  "amount_requested": 6540,
  "currency": "USD",
  "approved": true,
  "status": "Authorized",
  "auth_code": "643381",
  "response_code": "10000",
  "response_summary": "Approved",
  "3ds": {
    "enrolled": "Y",
    "upgrade_reason": "sca_retry"
  },
  "risk": {
    "flagged": true,
    "score": 22
  },
  "source": {
    "type": "card",
    "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
    "billing_address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "expiry_month": 6,
    "expiry_year": 2025,
    "name": "Bruce Wayne",
    "scheme": "VISA",
    "scheme_local": "Cartes_Bancaires",
    "local_schemes": [
      "cartes_bancaires",
      "visa"
    ],
    "last4": "9996",
    "fingerprint": "F639CAB2745BEE4140BF86DF6B6D6",
    "bin": "45434748",
    "card_type": "CREDIT",
    "card_category": "CONSUMER",
    "issuer": "GOTHAM STATE BANK",
    "issuer_country": "US",
    "product_id": "F",
    "product_type": "CLASSIC",
    "avs_check": "S",
    "cvv_check": "Y",
    "payment_account_reference": "EUNIX9AX7THOOJIEJ2AP6OOFAHGH4",
    "encrypted_card_number": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz...",
    "account_update_status": "card_updated",
    "account_update_failure_code": "VAU009"
  },
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "email": "johnsmith@example.com",
    "name": "John Smith",
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "summary": {
      "registration_date": "2023-05-01T00:00:00.0000000",
      "first_transaction_date": "2023-07-01T00:00:00.0000000",
      "last_payment_date": "2023-08-01T00:00:00.0000000",
      "total_order_count": 15,
      "last_payment_amount": 500,
      "is_premium_customer": true,
      "is_returning_customer": true,
      "lifetime_value": 500
    }
  },
  "balances": {
    "total_authorized": 6540,
    "available_to_void": 6540,
    "available_to_capture": 6540
  },
  "reference": "ORD-5023-4E89",
  "processing": {
    "retrieval_reference_number": "909913440644",
    "acquirer_transaction_id": "440644309099499894406",
    "recommendation_code": "02",
    "partner_order_id": "5GK24544NA744002L",
    "surcharge_amount": 200,
    "purchase_country": "GB",
    "foreign_retailer_amount": 200,
    "scheme_merchant_id": "123456",
    "reconciliation_id": "4123495123",
    "aggregator": {
      "sub_merchant_id": "9cf70789ba90123",
      "aggregator_id_visa": "10012345",
      "aggregator_id_mc": "00000123456"
    }
  },
  "eci": "06",
  "scheme_id": "489341065491658",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
    },
    "actions": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/actions"
    },
    "authorize": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/authorizations"
    },
    "void": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/voids"
    },
    "capture": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/capture"
    },
    "cancel": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/cancel"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.