Update a Payment Setup

​

Beta

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.

Path Parameters
  • id
    Type: string
    required

    The unique identifier of the Payment Setup to update.

Body·
required
application/json
  • processing_channel_id
    Type: string Pattern: ^(pc)_(\w{26})$
    required

    The processing channel to use for the payment.

  • amount
    Type: number
    required

    The payment amount, in the minor currency unit.

  • currency
    Type: string
    required

    The currency of the payment, as a three-letter ISO currency code.

  • presentment_details
    Type: object ·

    The amount and currency to present to the customer, when the settlement currency differs from the customer-facing currency.

  • payment_type
    Type: string enum

    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.

    values
    • regular
    • recurring
    • moto
    • installment
    • pay_later
    • unscheduled
  • reference
    Type: string
    max length:  
    80

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

  • description
    Type: string
    max length:  
    100

    A description of the payment.

  • payment_methods
    Type: object

    The payment methods that are enabled on your account and available for use.

  • settings
    Type: object

    Settings for the Payment Setup.

  • risk
    Type: object

    Risk assessment settings for the Payment Setup.

  • customer
    Type: object

    The customer's details.

  • order
    Type: object

    The customer's order details.

Responses
  • application/json
  • 401

    Authentication failed. Provide a valid API key or access token.

  • 403

    You do not have permission to update this Payment Setup.

  • application/json
Request Example for put/payments/setups/{id}
curl 'https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "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": {
      "id": "src_wmlfc3zttb4uzmk6snpwb43jbi"
    },
    "klarna": {
      "initialization": "disabled"
    },
    "stcpay": {
      "initialization": "disabled",
      "otp": "123456"
    },
    "tabby": {
      "initialization": "disabled",
      "payment_types": [
        "pay_later"
      ]
    },
    "qpay": {
      "national_id": "21234567890",
      "description": ""
    },
    "ideal": {
      "description": "2 t-shirts"
    },
    "knet": {
      "language": "en"
    },
    "bancontact": {
      "account_holder_name": ""
    },
    "blik": {
      "partner_code": "999111"
    },
    "alipay_cn": {
      "terminal_type": "web",
      "os_type": "android"
    },
    "alipay_hk": {
      "terminal_type": "web",
      "os_type": "android"
    },
    "gcash": {
      "terminal_type": "web",
      "os_type": "android"
    },
    "tng": {
      "terminal_type": "web",
      "os_type": "android"
    },
    "dana": {
      "terminal_type": "web",
      "os_type": "android"
    },
    "tamara": {
      "initialization": "disabled",
      "risk_assessment": {
        "premium_customer": false,
        "risk_score": 42,
        "order_count_last24h": 0,
        "linked_device_count": 2
      }
    },
    "multibanco": {
      "account_holder_name": ""
    },
    "kakaopay": {
      "terminal_type": "web",
      "os_type": "android"
    },
    "truemoney": {
      "terminal_type": "web",
      "os_type": "android"
    },
    "p24": {
      "account_holder": {
        "name": "",
        "email": ""
      }
    },
    "alma": {},
    "swish": {
      "billing_descriptor": "",
      "account_holder": {
        "first_name": "John",
        "last_name": "Smith"
      }
    },
    "sequra": {},
    "ach": {
      "account_type": "savings",
      "account_holder": {
        "type": "individual",
        "first_name": "",
        "last_name": "",
        "company_name": "",
        "date_of_birth": "",
        "identification": {
          "type": "",
          "issuing_country": "",
          "number": ""
        }
      },
      "account_number": "",
      "bank_code": "",
      "country": ""
    },
    "sepa": {
      "account_holder": {
        "type": "individual",
        "first_name": "",
        "last_name": "",
        "company_name": ""
      },
      "account_number": "",
      "country": "",
      "currency": "",
      "mandate": {
        "id": "",
        "type": "core",
        "date_of_signature": ""
      }
    },
    "bacs": {
      "initialization": "disabled",
      "account_holder": {
        "type": "individual",
        "first_name": "",
        "last_name": "",
        "company_name": "",
        "email": "john.smith@example.com"
      },
      "account_number": "",
      "bank_code": "",
      "country": "",
      "currency": "",
      "allow_partial_match": false
    },
    "paybybank": {
      "bank_id": "ob-natwest"
    },
    "paypal": {
      "initialization": "disabled",
      "user_action": "pay_now",
      "brand_name": "Acme Corporation",
      "shipping_preference": "no_shipping"
    },
    "cashapp": {
      "initialization": "disabled",
      "customer_profile_sharing": true
    },
    "googlepay": {
      "token_data": {
        "protocol_version": "",
        "signature": "",
        "signed_message": "",
        "tokenization_key": ""
      },
      "token": {
        "id": "",
        "expires_on": ""
      },
      "network_token": {
        "number": "",
        "expiry_month": 11,
        "expiry_year": 2030,
        "cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
        "eci": "07"
      },
      "store_for_future_use": true,
      "phone": {
        "country_code": "+44",
        "number": "207 946 0000"
      },
      "account_holder": {
        "type": "individual",
        "first_name": "",
        "last_name": "",
        "middle_name": "",
        "company_name": "",
        "account_name_inquiry": true
      },
      "preferred_scheme": "visa"
    },
    "applepay": {
      "token_data": {
        "version": "",
        "data": "",
        "signature": "",
        "header": {
          "ephemeral_public_key": "",
          "public_key_hash": "",
          "transaction_id": ""
        }
      },
      "token": {
        "id": "",
        "expires_on": ""
      },
      "network_token": {
        "number": "",
        "expiry_month": 11,
        "expiry_year": 2030,
        "cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
        "eci": "07"
      },
      "store_for_future_use": true,
      "phone": {
        "country_code": "+44",
        "number": "207 946 0000"
      },
      "account_holder": {
        "type": "individual",
        "first_name": "",
        "last_name": "",
        "middle_name": "",
        "company_name": "",
        "account_name_inquiry": true
      },
      "preferred_scheme": "visa"
    },
    "card": {
      "token": {
        "id": ""
      },
      "details": {
        "number": "",
        "expiry_month": 1,
        "expiry_year": 1,
        "name": "",
        "cvv": "",
        "stored": true,
        "allow_update": true
      },
      "store_for_future_use": true,
      "phone": {
        "country_code": "+44",
        "number": "207 946 0000"
      },
      "account_holder": {
        "type": "individual",
        "first_name": "",
        "last_name": "",
        "middle_name": "",
        "company_name": "",
        "account_name_inquiry": true
      },
      "preferred_scheme": "visa"
    },
    "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-01",
      "last_modified": "2023-05-01",
      "returning_customer": true,
      "first_transaction_date": "2023-09-15",
      "last_transaction_date": "2025-03-28",
      "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"
      },
      "method": "",
      "delay": 3
    },
    "sub_merchants": [
      {
        "id": "SUB12345",
        "product_category": "Electronics",
        "number_of_sales": 500,
        "registration_date": "2023-01-15"
      }
    ],
    "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-01",
          "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-31",
            "address": {
              "country": "GB"
            }
          }
        ],
        "flight_leg_details": [
          {
            "flight_number": "BA1483",
            "carrier_code": "BA",
            "class_of_travelling": "W",
            "departure_airport": "LHR",
            "departure_date": "2025-10-13",
            "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-11",
        "check_out_date": "2025-04-18",
        "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-19"
          }
        ],
        "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-01",
          "total_reservation_count": 150
        }
      }
    ]
  },
  "account_funding_transaction": {
    "enabled": true,
    "purpose": "financial_services",
    "sender": {
      "date_of_birth": "2000-01-01",
      "reference": "0fc88634-78c1-4286-9cb6-6ca358730c8c",
      "identification": {
        "type": "passport",
        "number": "1234567890",
        "issuing_country": "US"
      }
    },
    "recipient": {
      "date_of_birth": "2000-01-01",
      "account_number": "",
      "first_name": "",
      "last_name": "",
      "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+01:00"
  },
  "billing_descriptor": {
    "name": "Checkout.com",
    "city": "London",
    "reference": "Payment for order 123456"
  },
  "metadata": {
    "additionalProperty": ""
  }
}'
{
"id": "string",
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"amount": 10000,
"currency": "GBP",
"presentment_details": {
"amount": 110,
"currency": "EUR"
},
"payment_type": "regular",

Payment Setup updated.