Prerequisites

This covers the trust setup that must be established prior to any API call between Save to Pay (S2P) and the partner. Until this configuration is complete, no API call described in the Inbound and Outbound API documentation will succeed.

Partner Onboarding

Partner must fill out the Partner Information Request Form given by the Samsung development team.

The following information are required:

  1. Country

  2. Card type (example: PAYMENT)

  3. Card network (example: Visa, Mastercard)

  4. External IP address(es) for whitelisting (provide for both Staging and Production)

  5. Base URL for sending notifications (provide for both Staging and Production)

  6. Will the partner use the Save to Pay JavaScript Library? (YES or NO)

  7. How does the partner secure inbound calls to their notification endpoint? (mTLS / IP allowlisting / both)

  8. CSR Common Name (CN) (provide for both Staging and Production)

Trust Model Overview

There are two separate mTLS relationships, in opposite directions, signed by different Certificate Authorities.

Direction

Call

CA signing

Validation

APIs Covered

Inbound

Partner ➡️ S2P

Samsung’s PKI (partner submits a CSR, Samsung signs it)

Samsung’s API gateway

POST /registrationsGET /registrations/{regId}

Outbound

S2P ➡️ Partner

Partner’s own CA (partner issues the cert, hands it to Samsung)

Partner’s server

POST /notifications

Certificate Exchange Process

Inbound (Partner ➡️ S2P)

  1. Partner generates a Certificate Signing Request (CSR).

  2. Partner submits the CSR to Samsung during onboarding process.

  3. Samsung’s PKI signs and returns the client certificate.

  4. Partner installs the signed certificate in the HTTP client. This HTTP client is in their server and uses to call /registrations API.

  5. Separate certificates are issued for staging and production – A single certificate must not be used for both.

Outbound (S2P ➡️ Partner)

  1. Partner has their own CA – an existing internal CA is sufficient, and does not need to be a publicly trusted CA.

  2. Partner issues a client certificate by that CA

  3. Partner delivers the certificate (and the CA’s public root, if not already trusted) to Samsung.

  4. Samsung configures S2P to present this certificate when calling the partner’s /notifications endpoint.

  5. Partner configures its server/gateway to require and validate this client certificate on inbound connections. (HTTPS alone is not sufficient – the server must be configured for mutual authentication, not only for server-side TLS)

  6. Separate certificates for staging and production is recommended, similar to inbound process.

Rotation & Expiry

  • Track expiry dates for all four certificates (inbound x 2 environments, outbound x 2 environments)

  • Agree on certificate renewal lead time with Samsung’s onboarding team before go-live. This ensures a certificate never expires mid-flight, which would otherwise silently break provisioning.

  • Confirm the process for rotating a certificate without downtime, such as by overlapping validity windows.

Partner-id Issuance

partner-id is an identifier. It is sent as a plain header on every API inbound/outbound call.

Samsung issues a distinct partner-id for each combination of environment (staging and production), and card network.

Each partner-id is issued by Samsung during onboarding.

Environment

Card network #1

Card network #2

Staging

partner-id #1

partner-id #2

Production

partner-id #3

partner-id #4

Environment Matrix

Item

Staging

Production

Inbound base URL (Partner → S2P)

https://s2p-api.stg.mpay.samsung.com/ext/v1

https://s2p-api.mpay.samsung.com/ext/v1

Outbound notification URL (S2P → Partner)

[Partner to provide]

[Partner to provide]

partner-id

[Samsung to provide]

[Samsung to provide]

SDK CDN URL

https://d1ea2ye0qee75q.cloudfront.net/s2p/libs/js/${version}/s2p.min.js

https://spay.samsung.com/s2p/libs/js/${version}/s2p.min.js

Inbound client cert (issued by Samsung)

[Samsung to provide]

[Samsung to provide]

Outbound client cert (issued by Partner)

[Partner to provide]

[Partner to provide]

Required Headers

Header

Direction (Inbound/Outbound)

Description

Content-Type: application/json

Both

Payload format

Accept: application/json

Outbound only

Expected response format

partner-id

Both

Attribute issued by Samsung

request-id

Both

Unique ID attribute for a single attempt – a new value must be generated on every outbound retry