Request a payment or payout

​

Send a payment or payout.

Note: successful payout requests will always return a 202 response.

Headers
  • Cko-Idempotency-Key
    Type: string

    An optional idempotency key for safely retrying payment requests

Body
application/json
    • currency
      Type: string
      min length:  
      3
      max length:  
      3
      required

      The three-letter ISO currency code

    • source

      The source of the payment

      A card payment source

      • type
        Discriminator
        Type: string
        required
        • enum
          const:  
          card

          The payment source type.

          values
          • card
      • number
        Type: string
        required

        The card number (without separators)

      • expiry_month
        Type: integer
        min:  
        1
        max:  
        12
        required

        The expiry month of the card

      • expiry_year
        Type: integer
        required

        4-digit expiry year of the card

      • name
        Type: string

        The name of the cardholder

      • cvv
        Type: string
        min length:  
        3
        max length:  
        4

        The card verification value/code. 3 digits, except for American Express (4 digits)

      • stored
        Type: boolean

        Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to true when you provide card details that you already have on file for the customer.

      • store_for_future_use
        Type: boolean

        This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response.

      • billing_address
        Type: object ·

        The billing address of the cardholder

      • phone
        Type: object ·

        The phone number of the cardholder

      • account_holder
        Type: object

        Information about the account holder of the card

      • allow_update
        Type: boolean

        Specifies whether to use the Real-Time Account Updater to update the card information.

    • fallback_source
      Type: object ·

      A card payment source

    • amount
      Type: integer Format: int64
      min:  
      0
      max:  
      9999999999

      The payment amount. To perform a card verification, do not provide the amount or provide a value of 0.

      The amount must be provided in the minor currency unit.

    • payment_type
      Type: string enum

      The type of payment.

      This field is required for card payments in which the cardholder is not present. For example, mail orders, telephone orders, or merchant-initiated transactions (MITs) in a recurring payment series.

      For MITs, this field must not be set to Regular.

      values
      • Regular
      • Recurring
      • MOTO
      • Installment
      • PayLater
      • Unscheduled
    • payment_plan

      The details of a recurring subscription or installment

      • Type: object ·

        The information to process a recurring payment request. To be used when the payment_type is recurring.

        • amount_variability
          Type: string enum

          Specifies whether the amount is fixed or variable for each recurrence.

          values
          • Fixed
          • Variable
        • days_between_payments
          Type: integer

          Indicates the minimum number of days between payments

        • total_number_of_payments
          Type: integer

          Indicates the agreed total number of payments

        • current_payment_number
          Type: integer

          The number of the current installment payment

        • expiry
          Type: string

          The date after which no further payments will be performed in the format YYYYMMDD

        • name
          Type: string
          max length:  
          35

          The name of the payment plan.

          Required when source.type is blik. For Blik merchant-initiated requests using an external partner_agreement_id, this value is used as the Blik Alias Label.

        • start_date
          Type: string

          The date on which the first payment will be taken, in YYYYMMDD format.

          Required when source.type is blik and the recurring agreement is created without an initial payment (amount set to 0).

        • amount
          Type: integer
          min:  
          1

          The amount to charge for each payment in the plan, in the minor currency unit.

          Required when source.type is blik, payment_plan.amount_variability is Fixed, and the recurring agreement is created without an initial payment (amount set to 0).

    • merchant_initiated
      Type: boolean

      Whether the payment is a merchant-initiated transaction (MIT).

      Must be set to true for all MITs.

      If you set this field to true, the value for payment_type must not be set to Regular.

    • reference
      Type: string
      max length:  
      80

      A reference you can use to identify the payment. For example, an order number.

      • For Amex payments, the reference has a 30-character limit.
      • For Benefit payments, the reference must be a unique alphanumeric value.
      • For Blik payments, the reference has a 35-character limit.
      • For Discover payments, the reference has a 60-character limit.
      • For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit.
      • For OmanNet payments, the reference must be a unique alphanumeric value between 12 and 30 characters long, generated for every payment action.
      • For seQura payments, the reference is required and must be a unique value.
      • For TWINT payments, the reference has a 50 character limit.
    • description
      Type: string
      max length:  
      100

      A description of the payment.

    • authorization_type
      Type: string enum

      The authorization type

      values
      • Final
      • Estimated
    • partial_authorization
      Type: object ·

      Required information to allow partial authorization

    • capture
      Type: boolean

      Whether to capture the payment (if applicable)

    • capture_on
      Type: string · Format: date-time

      A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to true

    • expire_on
      Type: string · Format: date-time

      The date and time when the Multibanco payment expires in UTC.
      Format – ISO 8601
      Example– 2025-01-31T10:20:30.456

    • customer
      Type: object ·

      The customer's details. Required if source.type is tamara

    • billing_descriptor
      Type: object ·

      An optional description that is displayed on the customer's statement identifying a purchase.

    • shipping
      Type: object ·

      The shipping details.

    • 3ds

      Information required for 3D Secure authentication payments.

      Required information to process a 3DS authentication with the payment request

      • Required information to process a 3DS authentication with the payment request

    • authentication
      Type: object ·

      Provides information required to authenticate payments.

    • processing_channel_id
      Type: string Pattern: ^(pc)_(\w{26})$

      The processing channel to be used for the payment

    • previous_payment_id
      Type: string
      max length:  
      100

      An identifier that links the payment to an existing series of payments.

      You must only pass this field if the transaction is a merchant-initiated transaction (MIT) in a recurring payment series.

      To link the payment, pass one of the following as its value:

      • a payment identifier (for example, pay_cr4hxwizzp6k7biycuk2ibltnm) from the recurring series, or
      • the scheme transaction ID
    • risk
      Type: object ·

      Configures the risk assessment performed during the processing of the payment

    • success_url
      Type: string
      max length:  
      1024      Format: uri

      For redirect payment methods, this overrides the default success redirect URL configured on your account

    • failure_url
      Type: string
      max length:  
      1024      Format: uri

      For redirect payment methods, this overrides the default failure redirect URL configured on your account

    • payment_ip
      Type: string ·
      max length:  
      45      Format: ipv4
      deprecated

      Use the risk.device.network.ipv4 or risk.device.network.ipv6 field instead.

      The IP address used to make the payment. Used by Checkout.com's risk engine to check the customer's IP address – only accepts IPv4 and IPv6 addresses. Required if source.type is sequra

    • sender

      Information about the sender of the payment's funds

      Store a previously tokenized instrument

      • type
        Discriminator
        Type: string enum
        required

        The sender type. If set to instrument, the sender information (name and address) will be retrieved from the payment instrument.

        values
        • individual
        • corporate
        • instrument
      • first_name
        Type: string
        required

        The sender's first name

      • last_name
        Type: string
        required

        The sender's last name

      • address
        Type: object ·
        required

        The sender's address

      • reference
        Type: string

        The unique reference for the sender of the payment.

      • date_of_birth
        Type: string
        max length:  
        10        Format: date

        The sender's date of birth (yyyy-mm-dd)

      • identification
        Type: object
    • recipient
      Type: object ·

      Information about the recipient of the payment's funds. Relevant for Account Funding Transactions and VISA or Mastercard domestic UK transactions processed by financial institutions.

    • amount_allocations
      Type: array object[] · 1…50

      The sub-entities that the payment is being processed on behalf of

    • processing
      Type: object ·

      Use the processing object to influence or override the data sent during card processing

    • items
      Type: array object[] · …998

      The order's line items.

      The order's line item or product that is being purchased.

    • retry
      Type: object ·

      Configuration of asynchronous retries. For more information about asynchronous retries and supported response codes, see Configure scheduled retries.

    • subscription
      Type: object ·

      The details of the subscription.

    • metadata
      Type: object

      Stores additional information about a transaction with custom fields and up to five user-defined fields, which you can use for reporting purposes. The object supports string, number, and boolean fields, but not arrays or objects.

      You can provide up to 20 metadata fields per API call, but the value of each field must not exceed 255 characters in length.

      You can also reference metadata properties in your custom rules for Fraud Detection. For example, $coupon_code = '1234’.

    • segment
      Type: object ·

      The dimension details about business segment for payment request. At least one dimension required.

    • instruction
      Type: object

      Details about the payment instruction.

    • routing
      Type: object

      Controls processor attempts at the payment level.

Responses
  • application/json
  • application/json
  • 401

    Unauthorized

  • application/json
  • application/json
  • 502

    Bad gateway

Request Example for post/payments
curl 'https://{prefix}.api.sandbox.checkout.com/payments' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "source": {
    "number": "4543474002249996",
    "expiry_month": 6,
    "expiry_year": 2030,
    "name": "Bruce Wayne",
    "cvv": "956",
    "stored": true,
    "store_for_future_use": false,
    "billing_address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "state": "",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "account_holder": {},
    "allow_update": false,
    "type": "card"
  },
  "fallback_source": {
    "number": "4543474002249996",
    "expiry_month": 6,
    "expiry_year": 2030,
    "name": "Bruce Wayne",
    "cvv": "956",
    "stored": true,
    "store_for_future_use": false,
    "billing_address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "state": "",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "account_holder": {},
    "allow_update": false,
    "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
  },
  "merchant_initiated": true,
  "reference": "ORD-5023-4E89",
  "description": "Set of 3 masks",
  "authorization_type": "Estimated",
  "partial_authorization": {
    "enabled": true
  },
  "capture": true,
  "capture_on": "",
  "expire_on": "",
  "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-01",
      "first_transaction_date": "2023-07-01",
      "last_payment_date": "2023-08-01",
      "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",
    "reference": "",
    "local_descriptors": [
      {
        "name": "漢字",
        "character_set": null
      }
    ]
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "state": "",
      "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": "false",
    "challenge_indicator": "no_preference",
    "allow_upgrade": true,
    "exemption": "low_value"
  },
  "authentication": {
    "preferred_experiences": [
      "google_spa",
      "3ds"
    ]
  },
  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  "previous_payment_id": "pay_fun26akvvjjerahhctaq2uzhu4",
  "risk": {
    "enabled": false,
    "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",
        "tor": false,
        "vpn": false,
        "proxy": false
      },
      "provider": {
        "id": "1728646225211.AfUgxG",
        "name": "List [ \"merchant\", \"fingerprintjs\", \"riskify\" ]"
      },
      "timestamp": "2024-02-06T15:00:00.000Z",
      "timezone": "60",
      "virtual_machine": false,
      "incognito": false,
      "jailbroken": false,
      "rooted": false,
      "java_enabled": false,
      "javascript_enabled": false,
      "language": "FR-fr",
      "color_depth": "16",
      "screen_height": "1080",
      "screen_width": "1920",
      "user_agent_client_hint": "",
      "iframe_payment_allowed": true,
      "accept_header": ""
    }
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/fail",
  "sender": {
    "type": "individual",
    "reference": "",
    "first_name": "John",
    "last_name": "Jones",
    "date_of_birth": "1985-05-15",
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "state": "",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "identification": {
      "type": "driving_licence",
      "number": "1234",
      "issuing_country": "GT"
    }
  },
  "recipient": {
    "dob": "1985-05-15",
    "account_number": "5555554444",
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "state": "",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "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,
    "discount_amount": 0,
    "duty_amount": 0,
    "shipping_amount": 300,
    "shipping_tax_amount": 100,
    "aft": true,
    "preferred_scheme": "mastercard",
    "merchant_initiated_reason": "Delayed_charge",
    "campaign_id": 1,
    "product_type": "QR Code",
    "open_id": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
    "original_order_amount": 10,
    "receipt_id": "10",
    "terminal_type": "WAP",
    "os_type": "ANDROID",
    "invoice_id": "",
    "locale": "en-US",
    "airline_data": [
      {
        "ticket": {
          "number": "045-21351455613",
          "issue_date": "2023-05-20",
          "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-26",
            "address": {
              "country": "US"
            }
          }
        ],
        "flight_leg_details": [
          {
            "flight_number": "101",
            "carrier_code": "BA",
            "class_of_travelling": "J",
            "departure_airport": "LHR",
            "departure_date": "2023-06-19",
            "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-20",
        "check_out_date": "2023-06-23",
        "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-14"
          }
        ],
        "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"
          }
        ]
      }
    ],
    "merchant_callback_url": "",
    "line_of_business": "Flights",
    "pan_preference": "fpan",
    "service_type": "standard",
    "partner_code": "902111",
    "provision_network_token": true,
    "card_type": "credit",
    "affiliate_id": "",
    "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"
    },
    "scheme_transaction_link_id": ""
  },
  "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,
      "tax_exempt": true,
      "discount_amount": 1000,
      "wxpay_goods_id": "1001",
      "url": "",
      "image_url": "",
      "service_ends_on": "2025-01-01",
      "purchase_country": "GB",
      "foreign_retailer_amount": 200
    }
  ],
  "retry": {
    "enabled": true,
    "dunning": {
      "enabled": true,
      "max_attempts": 6,
      "end_after_days": 30
    },
    "downtime": {
      "enabled": true
    }
  },
  "subscription": {
    "id": ""
  },
  "metadata": {
    "coupon_code": "NY2018"
  },
  "segment": {
    "brand": "Acme Corporation",
    "business_category": "Inward Payments",
    "market": "UK"
  },
  "instruction": {
    "purpose": "donations"
  },
  "routing": {
    "attempts": [
      {
        "scheme": "accel"
      }
    ]
  }
}'

{
  "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": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "state": "GB",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "scheme": "Visa",
    "last4": "6584",
    "fingerprint": "B16D9C2EF0C861A8825C9BD59CCE9171D84EBC45E89CC792B5D1D2D0DDE3DAB7",
    "bin": "448504",
    "card_type": "CREDIT",
    "card_category": "COMMERCIAL",
    "issuer": "GE CAPITAL FINANCIAL, INC.",
    "issuer_country": "US",
    "product_type": "PURCHASING",
    "avs_check": "G",
    "cvv_check": "Y",
    "payment_account_reference": "V001898055688657091"
  },
  "customer": {
    "id": "cus_udst2tfldj6upmye2reztkmm4i",
    "email": "johnsmith@example.com",
    "name": "John Smith",
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    }
  },
  "processed_on": "2019-09-10T10:11:12Z",
  "reference": "ORD-5023-4E89",
  "processing": {
    "retrieval_reference_number": "909913440644",
    "acquirer_transaction_id": "440644309099499894406",
    "recommendation_code": "02",
    "partner_order_id": "5GK24544NA744002L",
    "scheme_merchant_id": "123456"
  },
  "eci": "06",
  "scheme_id": "489341065491658",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
    },
    "void": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
    },
    "capture": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
    }
  }
}

Payment processed successfully