# Samsung Pay for Unified Payments API

To accept Samsung Pay payments, you must:

1. Retrieve the Samsung Pay payment credential. Optionally, tokenize the credential using a Checkout.com payment token.
2. Request a Samsung Pay payment.

---

## Before you start

Contact your account manager to enable Samsung Pay on your account, and to get your Checkout.com entity ID.

---

## Retrieve the Samsung Pay payment credential

Use Samsung's Web Checkout SDK to get the payment credential. Samsung does not provide a server-to-server method to create the credential, so you must open the Samsung Pay payment screen in the customer's browser.

When the customer approves the payment, Samsung returns the credential as a compact JSON Web Encryption (JWE) payload.

> **Note**
>
> Do not write the Samsung Pay payload to your logs. It contains sensitive payment data.

You can decrypt the payload and request a payment using the network token details, or you can tokenize the credential using a Checkout.com payment token.

---

## Generate a Checkout.com token from the Samsung Pay token (optional)

When you receive the payload from Samsung, call the [Request a token](https://api-reference.checkout.com/tag/Tokens/#operation/requestAToken) endpoint. We decrypt the credential, store the wallet data, and return a Checkout.com token that starts with `tok_`.

> **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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/tokens`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/tokens`

In your request:

- Set `type` to `samsungpay`.
- Provide the Samsung payload in the `token_data` object, using one of the following formats:

### Request example

```json
{
  "type": "samsungpay",
  "token_data": {
    "data": "<samsung-compact-jwe>"
  }
}
```

Replace `<samsung-compact-jwe>` with the payload that Samsung returned.

### Response example

```json
{
  "type": "samsungpay",
  "token": "tok_ymu4qlccztkedmd6b7c3hcf6ae",
  "expires_on": "2019-10-21T10:48:35Z",
  "expiry_month": 8,
  "expiry_year": 2023,
  "scheme": "Visa",
  "last4": "6222",
  "bin": "481891",
  "card_type": "DEBIT",
  "card_category": "CONSUMER",
  "issuer": "Test Bank",
  "issuer_country": "GB",
  "product_id": "F",
  "product_type": "Visa Classic"
}
```

Use the value from the `token` field of the response in your payment request.

---

## Request a payment

**Using the Checkout.com token**

Call the [Request a payment](https://api-reference.checkout.com/tag/Payments#operation/requestAPaymentOrPayout) endpoint, providing the following fields:

- `source.type` set to `token`
- `source.token` set to the `tok_` token you received when you tokenized the credential

> **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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "source": {
    "type": "token",
    "token": "tok_ubfj2q76miwundwlk72vxt2i7q"
  },
  "amount": 6540,
  "currency": "GBP"
}
```

**Using a pre-decrypted Samsung Pay token**

After you decrypt the Samsung Pay network token details, you can use the decrypted values to request a payment without tokenizing the credential.

Call the [Request a payment](https://api-reference.checkout.com/tag/Payments#operation/requestAPaymentOrPayout) endpoint, providing the following fields:

- `source.type` set to `network_token`
- `source.token_type` set to `samsungpay`
- `source.token`, `source.expiry_month`, `source.expiry_year`, `source.eci`, and `source.cryptogram` set to the matching values from the decrypted Samsung Pay payload

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "source": {
    "type": "network_token",
    "token": "4242424242424242",
    "token_type": "samsungpay",
    "expiry_month": "10",
    "expiry_year": "2025",
    "eci": "06",
    "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA"
  },
  "amount": 1000,
  "currency": "USD"
}
```

### Response example

If the `approved` field is `true`, your authorization was successful. A failed authorization can indicate the payment used an invalid or expired card, or a card with an insufficient available balance.

Handle errors and timeouts in your integration, and wait for a [Gateway](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Gateway) webhook before you start your order fulfillment process.

---

## Test Samsung Pay

To test Samsung Pay payments, first [create a test Checkout.com account](https://www.checkout.com/get-test-account).

Complete a test payment in your sandbox environment, and confirm that we accept the credential and process the payment. Resolve any domain, account setup, or credential submission issues before you go live.