Access1

Address Document Verification8

Agentic Commerce Protocol1

AML Screening2

Apple Pay3

Applicants4

Bacs Direct Debit1

Balances2

Business details2

Card metadata1

Card testing5

Cardholder access tokens1

Cardholders4

Cards11

Compliance requests2

Control groups4

Control profiles7

Controls5

Customers4

Digital cards1

Disputes12

Face Authentication7

Financial actions1

Flow3

Forex1

Forward6

Google Pay4

Hosted Payments Page2

ID Document Verification8

Identity Verification9

Instruments5

Inventory15

Issuing disputes6

Network Tokens4

Onboarding6

Onboarding Simulator5

Out-of-band authentication simulator1

Payment Context2

Payment instruments4

Payment Links2

Payment Methods1

Payment Setups4

Payments11

Payout schedules2

platforms4

Platforms4

Reports3

Representatives2

Standalone5

Standalone Account Updater1

Tokens2

Transactions2

Transfers2

Workflows21

Payment Setups

Update a Payment Setup

Updates a Payment Setup.

Update the Payment Setup whenever there are significant changes in the data relevant to the customer's transaction. For example, when the customer makes a change that impacts the total payment amount.

put/payments/setups/{id}

Request

Base URL
https://{prefix}.api.sandbox.checkout.com
Auth
- OAuth 2
  Client credentials
  Token URLstring
  Scopesgateway, gateway:payment, vault
- or API key in header Authorization
TypeScript
https://skmtc.dev/checkout/apis/checkout-com-api-reference/docs/payments/setups/:id/put.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

idstring required

The unique identifier of the Payment Setup to update.

Request body

idstring

processing_channel_idstring required

The processing channel to use for the payment.

amountnumber required

The payment amount, in the <a href="https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value" target="_blank">minor currency unit</a>.

currencystring required

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

The type of payment.

You must provide this field for card payments in which the cardholder is not present. For example, if the transaction is a recurring payment, or a mail order/telephone order (MOTO) payment.

referencestring

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

descriptionstring

A description of the payment.

available_payment_methodsstring[]

An ordered list of available payment method names. The order indicates the recommended presentation priority, with the first item being the highest priority.

metadataobject

A set of key/value pairs you can attach to a payment. It can be useful for storing additional information about the payment.

Example request

{
  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  "amount": 10000,
  "currency": "GBP",
  "presentment_details": {
    "amount": 110,
    "currency": "EUR"
  },
  "payment_type": "regular",
  "reference": "REF-0987-475",
  "description": "Set of 3 t-shirts",
  "payment_methods": {
    "auto_confirm": "card",
    "instrument": {
      "status": "ready",
      "id": "src_wmlfc3zttb4uzmk6snpwb43jbi",
      "type": "bacs"
    },
    "klarna": {
      "status": "ready",
      "action": {
        "client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJzZXNzaW9uX2lkIiA6ICIw",
        "session_id": "0b1d9815-165e-42e2-8867-35bc03789e00"
      },
      "iban": "DE89370400440532013000"
    },
    "stcpay": {
      "status": "ready",
      "otp": "123456"
    },
    "tabby": {
      "status": "ready",
      "payment_types": [
        "pay_later"
      ]
    },
    "bizum": {
      "status": "ready"
    },
    "paynow": {
      "status": "ready"
    },
    "qpay": {
      "status": "ready",
      "national_id": "21234567890"
    },
    "eps": {
      "status": "ready"
    },
    "ideal": {
      "status": "ready",
      "description": "2 t-shirts"
    },
    "knet": {
      "status": "ready"
    },
    "bancontact": {
      "status": "ready"
    },
    "benefit": {
      "status": "ready"
    },
    "blik": {
      "status": "ready",
      "partner_code": "999111"
    },
    "vipps": {
      "status": "ready"
    },
    "twint": {
      "status": "ready"
    },
    "alipay_cn": {
      "status": "ready",
      "terminal_type": "web",
      "os_type": "android"
    },
    "alipay_hk": {
      "status": "ready",
      "terminal_type": "web",
      "os_type": "android"
    },
    "gcash": {
      "status": "ready",
      "terminal_type": "web",
      "os_type": "android"
    },
    "tng": {
      "status": "ready",
      "terminal_type": "web",
      "os_type": "android"
    },
    "dana": {
      "status": "ready",
      "terminal_type": "web",
      "os_type": "android"
    },
    "mobilepay": {
      "status": "ready"
    },
    "tamara": {
      "status": "ready",
      "risk_assessment": {
        "risk_score": 42,
        "linked_device_count": 2
      }
    },
    "mbway": {
      "status": "ready"
    },
    "multibanco": {
      "status": "ready"
    },
    "wechatpay": {
      "status": "ready"
    },
    "kakaopay": {
      "status": "ready",
      "terminal_type": "web",
      "os_type": "android"
    },
    "truemoney": {
      "status": "ready",
      "terminal_type": "web",
      "os_type": "android"
    },
    "octopus": {
      "status": "ready"
    },
    "p24": {
      "status": "ready"
    },
    "alma": {
      "status": "ready"
    },
    "swish": {
      "status": "ready",
      "account_holder": {
        "first_name": "John",
        "last_name": "Smith"
      }
    },
    "sequra": {
      "status": "ready"
    },
    "ach": {
      "status": "ready"
    },
    "sepa": {
      "status": "ready"
    },
    "bacs": {
      "status": "ready",
      "instrument_id": "src_wkq7552u245upl5h75x24554xy",
      "account_holder": {
        "email": "john.smith@example.com"
      }
    },
    "paybybank": {
      "status": "ready",
      "bank_id": "ob-natwest",
      "action": {
        "banks": [
          {
            "bank_id": "ob-natwest",
            "display_name": "NatWest",
            "logo_url": "https://cdn.token.io/banks/natwest.png",
            "available": true
          }
        ]
      }
    },
    "paypal": {
      "status": "ready",
      "user_action": "pay_now",
      "brand_name": "Acme Corporation",
      "shipping_preference": "no_shipping",
      "action": {
        "type": "sdk",
        "order_id": "dd4b1a85-31de-404b-99f4-f143f8ba35ba"
      }
    },
    "cashapp": {
      "status": "ready",
      "customer_profile": {
        "customer_id": "CST_AYVkuLzfsRqEhf4OyQFxQNv22m7IjNFjO6f2J5CDE2nxAC4-21wJ2H8_2kvsdIsDZMN4",
        "cashtag": "$CASHTAG_C_TOKEN",
        "reference_id": "value",
        "full_name": "John Middle Doe",
        "given_name": "John",
        "middle_name": "Middle",
        "family_name": "Doe",
        "suffix": "Jr.",
        "birth_date": "1990-01-01T00:00:00.0000000",
        "address": {
          "address_line_1": "123 Main St",
          "locality": "Springfield",
          "administrative_district_level_1": "IL",
          "postal_code": "62701",
          "country": "US"
        },
        "phone_number": "5555555555",
        "email_address": "cash@cash.com",
        "customer_since": "1970-01-18T12:46:04.8000000+00:00"
      },
      "reference": "ORDER-99",
      "action": {
        "type": "redirect",
        "redirect_url": "https://sandbox.api.cash.app/customer-request/v1/requests/GRR_f5xg6wrxhtv3p4w24g0wrexa/interstitial?validity_token=bap03y"
      }
    },
    "googlepay": {
      "status": "ready",
      "network_token": {
        "expiry_month": 11,
        "expiry_year": 2030,
        "cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
        "eci": "07"
      },
      "phone": {
        "country_code": "+44",
        "number": "207 946 0000"
      }
    },
    "applepay": {
      "status": "ready",
      "network_token": {
        "expiry_month": 11,
        "expiry_year": 2030,
        "cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
        "eci": "07"
      },
      "phone": {
        "country_code": "+44",
        "number": "207 946 0000"
      }
    },
    "card": {
      "status": "ready",
      "phone": {
        "country_code": "+44",
        "number": "207 946 0000"
      }
    },
    "stablecoin": {
      "status": "ready"
    }
  },
  "available_payment_methods": [
    "card",
    "klarna",
    "stcpay",
    "stablecoin"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/fail",
    "capture": true,
    "excluded_payment_methods": [
      "card",
      "klarna",
      "stcpay"
    ]
  },
  "risk": {
    "enabled": true
  },
  "customer": {
    "country": "GB",
    "id": "cus_123456789",
    "email": {
      "address": "johnsmith@example.com",
      "verified": true
    },
    "name": "John Smith",
    "tax_number": "GB123456789",
    "phone": {
      "country_code": "+44",
      "number": "207 946 0000"
    },
    "device": {
      "locale": "en_GB",
      "fingerprint": "fp_abc123xyz",
      "ipv4": "203.0.113.0",
      "ipv6": "2001:db8:85a3::8a2e:370:7334",
      "client": "web",
      "os": "android"
    },
    "merchant_account": {
      "id": "1234",
      "registration_date": "2023-05-01T00:00:00.0000000",
      "last_modified": "2023-05-01T00:00:00.0000000",
      "first_transaction_date": "2023-09-15T00:00:00.0000000",
      "last_transaction_date": "2025-03-28T00:00:00.0000000",
      "total_order_count": 6,
      "last_payment_amount": 55.99
    }
  },
  "order": {
    "items": [
      {
        "name": "Battery Power Pack",
        "quantity": 1,
        "unit_price": 1000,
        "total_amount": 1000,
        "reference": "BA67A",
        "discount_amount": 150,
        "url": "https://example.com/products/my-item",
        "image_url": "https://example.com/products/my-item/image",
        "type": "digital",
        "category": "electronics"
      }
    ],
    "shipping": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com",
      "phone": {
        "country_code": "+44",
        "number": "207 946 0000"
      },
      "address": {
        "address_line1": "10 Canterbury Road",
        "address_line2": "Flat 2",
        "city": "London",
        "state": "Greater London",
        "zip": "NE1 1KO",
        "country": "GB"
      },
      "delay": 3
    },
    "sub_merchants": [
      {
        "id": "SUB12345",
        "product_category": "Electronics",
        "number_of_sales": 500,
        "registration_date": "2023-01-15T00:00:00.0000000"
      }
    ],
    "invoice_id": "inv_123456789",
    "shipping_amount": 5,
    "discount_amount": 10,
    "tax_amount": 2,
    "tipping_amount": 2,
    "surcharge_amount": 2,
    "amount_allocations": [
      {
        "id": "ent_w4jelhppmfiufdnatam37wrfc4",
        "amount": 1000,
        "reference": "ORD-5023-4E89",
        "commission": {
          "amount": 1000,
          "percentage": 1.125
        }
      }
    ]
  },
  "billing": {
    "address": {
      "address_line1": "10 Canterbury Road",
      "address_line2": "Flat 2",
      "city": "London",
      "state": "Greater London",
      "zip": "NE1 1KO",
      "country": "GB"
    }
  },
  "industry": {
    "airline": [
      {
        "ticket": {
          "number": "0742464639523",
          "issue_date": "2025-05-01T00:00:00.0000000",
          "issuing_carrier_code": "042",
          "travel_package_indicator": "A",
          "travel_agency_name": "Checkout Travel Agents",
          "travel_agency_code": "91114362"
        },
        "passengers": [
          {
            "first_name": "John",
            "last_name": "Smith",
            "date_of_birth": "1990-10-31T00:00:00.0000000",
            "address": {
              "country": "GB"
            }
          }
        ],
        "flight_leg_details": [
          {
            "flight_number": "BA1483",
            "carrier_code": "BA",
            "class_of_travelling": "W",
            "departure_airport": "LHR",
            "departure_date": "2025-10-13T00:00:00.0000000",
            "departure_time": "18:30",
            "arrival_airport": "JFK",
            "stop_over_code": "X",
            "fare_basis_code": "WUP14B"
          }
        ],
        "total_number_of_passengers": 1,
        "travel_type": "international",
        "trip_type": "one_way",
        "refundable": true,
        "delivery_recipient": "jane.smith@example.com",
        "ancillaries": "extra_baggage",
        "insurance": {
          "type": "travel",
          "company": "AXA",
          "price": {
            "amount": 500,
            "currency": "SAR"
          }
        }
      }
    ],
    "accommodation": [
      {
        "name": "Checkout Lodge",
        "booking_reference": "REF9083748",
        "check_in_date": "2025-04-11T00:00:00.0000000",
        "check_out_date": "2025-04-18T00:00:00.0000000",
        "address": {
          "address_line1": "123 High Street",
          "city": "London",
          "state": "Greater London",
          "country": "GB",
          "zip": "NE1 1CK"
        },
        "number_of_rooms": 2,
        "guests": [
          {
            "first_name": "John",
            "last_name": "Smith",
            "date_of_birth": "1970-03-19T00:00:00.0000000"
          }
        ],
        "room": [
          {
            "rate": 42.3,
            "number_of_nights": 5,
            "type": "deluxe"
          }
        ],
        "total_number_of_guests": 2,
        "refundable": true,
        "delivery_recipient": "jane.smith@example.com",
        "host": {
          "registration_date": "2020-01-01T00:00:00.0000000",
          "total_reservation_count": 150
        }
      }
    ]
  },
  "account_funding_transaction": {
    "enabled": true,
    "purpose": "financial_services",
    "sender": {
      "date_of_birth": "2000-01-01T00:00:00.0000000",
      "reference": "0fc88634-78c1-4286-9cb6-6ca358730c8c",
      "identification": {
        "number": "1234567890",
        "issuing_country": "US"
      }
    },
    "recipient": {
      "date_of_birth": "2000-01-01T00:00:00.0000000",
      "address": {
        "address_line1": "10 Canterbury Road",
        "address_line2": "Flat 2",
        "city": "London",
        "state": "Greater London",
        "zip": "NE1 1KO",
        "country": "GB"
      }
    }
  },
  "terminal": {
    "id": "12345678",
    "local_date_time": "2026-05-26T13:05:14.0000000+01:00"
  },
  "billing_descriptor": {
    "name": "Checkout.com",
    "city": "London",
    "reference": "Payment for order 123456"
  },
  "latest_payment": {
    "id": "pay_mbabizu24mvu3mela5njyhpit4",
    "source": {
      "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"
    },
    "destination": {
      "type": "bank_account"
    },
    "amount": 6540,
    "amount_requested": 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",
    "approved": true,
    "status": "Authorized",
    "balances": {
      "total_authorized": 6540,
      "available_to_void": 6540,
      "available_to_capture": 6540
    },
    "3ds": {
      "enrolled": "Y",
      "signature_valid": "Y",
      "cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
      "xid": "MDAwMDAwMDAwMDAwMDAwMzIyNzY=",
      "version": "2.1.0",
      "exemption": "low_value",
      "challenged": true,
      "upgrade_reason": "sca_retry",
      "trusted_listing": {
        "status": "Y",
        "source": "01"
      }
    },
    "authentication": {
      "experience": "3ds"
    },
    "risk": {
      "flagged": true,
      "score": 22
    },
    "customer": {
      "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
      "email": "brucewayne@gmail.com",
      "name": "Bruce Wayne",
      "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": {
      "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"
      }
    },
    "payment_ip": "90.197.169.245",
    "sender": {
      "type": "instrument",
      "reference": "8285282045818",
      "first_name": "John",
      "last_name": "Jones",
      "address": {
        "address_line1": "123 High St.",
        "address_line2": "Flat 456",
        "city": "London",
        "zip": "SW1A 1AA",
        "country": "GB"
      }
    },
    "amount_allocations": [
      {
        "id": "ent_w4jelhppmfiufdnatam37wrfc4",
        "amount": 1000,
        "reference": "ORD-5023-4E89",
        "commission": {
          "amount": 1000,
          "percentage": 1.125
        }
      }
    ],
    "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"
    },
    "processing": {
      "preferred_scheme": "cartes_bancaires",
      "app_id": "com.iap.linker_portal",
      "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"
            }
          ]
        }
      ],
      "partner_customer_id": "2102209000001106125F8",
      "partner_payment_id": "440644309099499894406",
      "partner_code": "999111",
      "failure_code": "partner_error",
      "partner_response_code": "ER_WRONG_TICKET",
      "tax_amount": 1000,
      "locale": "en-US",
      "retrieval_reference_number": "909913440644",
      "partner_merchant_advice_code": "24",
      "merchant_category_code": "5311",
      "scheme_merchant_id": "123456",
      "scheme": "ACCEL"
    },
    "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",
      "partner_id": 123989
    },
    "eci": "06",
    "scheme_id": "488341541494658",
    "actions": [
      {
        "id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
        "response_code": "10000",
        "response_summary": "Approved"
      }
    ],
    "instruction": {
      "purpose": "financial_services"
    },
    "_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"
      },
      "refund": {
        "href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/refund"
      }
    }
  }
}

Response

Payment Setup updated.