Samsung Pay for Payment Setup API
Beta

Last updated: November 4, 2026

To accept Samsung Pay payments, you must:

Create a payment setup.
Update the payment setup with the Samsung Pay token.
Confirm the payment.

Call the Create a payment setup endpoint.

Information

The Payment Setup API supports idempotency. You can safely retry API requests without the risk of duplicate requests.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payments/setups


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "GBP",
4  "amount": 2000,
5  "reference": "ORDER_01234",
6  "description": "Samsung Pay payment",
7  "payment_type": "regular",
8  "settings": {
9    "success_url": "https://example.com/payments/success",
10    "failure_url": "https://example.com/payments/failure"
11  }
12}

In the request body, provide the following:

processing_channel_id – The processing channel's unique identifier
amount – The payment amount
currency – The payment currency


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 2000,
5  "currency": "GBP",
6  "payment_type": "regular",
7  "reference": "ORDER_01234",
8  "description": "Samsung Pay payment",
9  "payment_methods": {
10    "samsungpay": {
11      "status": "action_required",
12      "flags": [
13        "token_required"
14      ]
15    }
16  },
17  "available_payment_methods": [
18    "samsungpay"
19  ],
20  "settings": {
21    "success_url": "https://example.com/payments/success",
22    "failure_url": "https://example.com/payments/failure"
23  }
24}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

For Samsung Pay, payment_methods contains the following fields:

status – The status of the payment method.
flags – An array of error codes or indicators that highlight missing or invalid information. The token_required flag indicates that you must provide a Checkout.com token.

When the customer selects Samsung Pay as the payment method on the checkout page:

Retrieve the Samsung Pay payment credential and tokenize it with a Checkout.com token. For more information, see Samsung Pay for Unified Payments API.
Call the Update a payment setup endpoint to submit the token.

Provide the following fields:

Field Description

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`currency` string	Three-letter ISO 4217 currency code. Required
`payment_methods.samsungpay.token` object	The Checkout.com Samsung Pay token. If you do not provide it, the payment method returns the `action_required` status and the `token_required` flag. Required
`processing_channel_id` string	The processing channel's unique identifier. Pattern: `^(pc)_(\w{26})$` Required
`settings.failure_url` string	The URL to redirect the customer after a failed authorization. Format: `uri` Required
`settings.success_url` string	The URL to redirect the customer after a successful authorization. Format: `uri` Required
`billing_descriptor.city` string	The city from which the payment was made. Min length: 1 Max length: 13 Conditional Required if `billing_descriptor` is provided.
`billing_descriptor.name` string	A dynamic description of the payment. Min length: 1 Max length: 25 Conditional Required if `billing_descriptor` is provided.
`payment_methods.samsungpay.account_holder.company_name` string	The account holder's company name. Conditional Required if `payment_methods.samsungpay.account_holder.type` is `corporate` or `government`.
`payment_methods.samsungpay.account_holder.first_name` string	The account holder's first name. Conditional Required if `payment_methods.samsungpay.account_holder.type` is `individual`.
`payment_methods.samsungpay.account_holder.last_name` string	The account holder's last name. Conditional Required if `payment_methods.samsungpay.account_holder.type` is `individual`.
`payment_methods.samsungpay.token.id` string	The token identifier, prefixed by `tok_`. Pattern: `^(tok)_(\w{26})$` Conditional Required if `payment_methods.samsungpay.token` is provided.
`billing.address.address_line1` string	The first line of the billing address.
`billing.address.address_line2` string	The second line of the billing address.
`billing.address.city` string	The city of the billing address.
`billing.address.country` string	The two-letter ISO 3166 country code of the billing address.
`billing.address.state` string	The state of the billing address.
`billing.address.zip` string	The zip or postal code of the billing address.
`billing_descriptor` object	The billing descriptor shown on the customer's statement.
`billing_descriptor.reference` string	The reference shown on the statement. Max length: 50
`customer.email.address` string	The customer's email address.
`customer.id` string	The customer's unique identifier.
`customer.phone.country_code` string	The international dialing code for the customer's phone number.
`customer.phone.number` string	The customer's phone number.
`description` string	A description of the payment. Max length: 100
`payment_methods.samsungpay.account_holder` object	The Samsung Pay account holder details.
`payment_methods.samsungpay.account_holder.account_name_inquiry` boolean	Indicates whether to perform an account name inquiry.
`payment_methods.samsungpay.account_holder.middle_name` string	The account holder's middle name.
`payment_methods.samsungpay.account_holder.type` string	The account holder type. Supported values: `individual` `corporate` `government`
`payment_methods.samsungpay.store_for_future_use` boolean	Indicates whether to store the payment details for future use. If set to `false`, the payment response does not include a payment instrument.
`payment_methods.samsungpay.token.expires_on` string	The date and time at which the token expires. Format: date-time
`payment_type` string	The type of payment. Supported values: `regular` `recurring` `installment` `unscheduled`
`reference` string	The payment reference. Max length: 80

amount

number

The payment amount, in the minor currency unit.
Minimum: 1
Required

currency

string

Three-letter ISO 4217 currency code.
Required

payment_methods.samsungpay.token

object

The Checkout.com Samsung Pay token. If you do not provide it, the payment method returns the action_required status and the token_required flag.
Required

processing_channel_id

string

The processing channel's unique identifier.
Pattern: ^(pc)_(\w{26})$
Required

settings.failure_url

string

The URL to redirect the customer after a failed authorization.
Format: uri
Required

settings.success_url

string

The URL to redirect the customer after a successful authorization.
Format: uri
Required

billing_descriptor.city

string

The city from which the payment was made.
Min length: 1
Max length: 13
Conditional
Required if billing_descriptor is provided.

billing_descriptor.name

string

A dynamic description of the payment.
Min length: 1
Max length: 25
Conditional
Required if billing_descriptor is provided.

payment_methods.samsungpay.account_holder.company_name

string

The account holder's company name.
Conditional
Required if payment_methods.samsungpay.account_holder.type is corporate or government.

payment_methods.samsungpay.account_holder.first_name

string

The account holder's first name.
Conditional
Required if payment_methods.samsungpay.account_holder.type is individual.

payment_methods.samsungpay.account_holder.last_name

string

The account holder's last name.
Conditional
Required if payment_methods.samsungpay.account_holder.type is individual.

payment_methods.samsungpay.token.id

string

The token identifier, prefixed by tok_.
Pattern: ^(tok)_(\w{26})$
Conditional
Required if payment_methods.samsungpay.token is provided.

billing.address.address_line1

string

The first line of the billing address.

billing.address.address_line2

string

The second line of the billing address.

billing.address.city

string

The city of the billing address.

billing.address.country

string

The two-letter ISO 3166 country code of the billing address.

billing.address.state

string

The state of the billing address.

billing.address.zip

string

The zip or postal code of the billing address.

billing_descriptor

object

The billing descriptor shown on the customer's statement.

billing_descriptor.reference

string

The reference shown on the statement.
Max length: 50

customer.email.address

string

The customer's email address.

customer.id

string

The customer's unique identifier.

customer.phone.country_code

string

The international dialing code for the customer's phone number.

customer.phone.number

string

The customer's phone number.

description

string

A description of the payment.
Max length: 100

payment_methods.samsungpay.account_holder

object

The Samsung Pay account holder details.

payment_methods.samsungpay.account_holder.account_name_inquiry

boolean

Indicates whether to perform an account name inquiry.

payment_methods.samsungpay.account_holder.middle_name

string

The account holder's middle name.

payment_methods.samsungpay.account_holder.type

string

The account holder type.
Supported values:

individual
corporate
government

payment_methods.samsungpay.store_for_future_use

boolean

Indicates whether to store the payment details for future use. If set to false, the payment response does not include a payment instrument.

payment_methods.samsungpay.token.expires_on

string

The date and time at which the token expires.
Format: date-time

payment_type

string

The type of payment.
Supported values:

regular
recurring
installment
unscheduled

reference

string

The payment reference.
Max length: 80


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "GBP",
4  "amount": 2000,
5  "reference": "ORDER_01234",
6  "description": "Samsung Pay payment",
7  "payment_type": "regular",
8  "settings": {
9    "success_url": "https://example.com/payments/success",
10    "failure_url": "https://example.com/payments/failure"
11  },
12  "payment_methods": {
13    "samsungpay": {
14      "token": {
15        "id": "tok_hilxnnylkxtutoswkxx2425lzi",
16        "expires_on": "2026-11-02T16:12:05Z"
17      }
18    }
19  }
20}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 2000,
5  "currency": "GBP",
6  "payment_type": "regular",
7  "reference": "ORDER_01234",
8  "description": "Samsung Pay payment",
9  "payment_methods": {
10    "samsungpay": {
11      "status": "ready",
12      "flags": [],
13      "token": {
14        "id": "tok_hilxnnylkxtutoswkxx2425lzi",
15        "expires_on": "2026-11-02T16:12:05Z"
16      }
17    }
18  },
19  "available_payment_methods": [
20    "samsungpay"
21  ],
22  "settings": {
23    "success_url": "https://example.com/payments/success",
24    "failure_url": "https://example.com/payments/failure"
25  }
26}

The response returns a ready status when the token has been successfully validated. The payment is ready to confirm.

If the token has expired, the response returns an invalid status with the token_expired flag. Tokenize the Samsung Pay credential again and resubmit the new token.

When the payment status changes to ready, confirm the payment by calling the Confirm a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
samsungpay as the {payment_method_name} path parameter.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/samsungpay

Samsung Pay for Payment Setup API
Beta

Create a payment setup

Information

Information

Request example

Response example

Update the payment setup

Request example

Response example

Confirm the payment