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:
Country
Card type (example: PAYMENT)
Card network (example: Visa, Mastercard)
External IP address(es) for whitelisting (provide for both Staging and Production)
Base URL for sending notifications (provide for both Staging and Production)
Will the partner use the Save to Pay JavaScript Library? (YES or NO)
How does the partner secure inbound calls to their notification endpoint? (mTLS / IP allowlisting / both)
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)
Partner generates a Certificate Signing Request (CSR).
Partner submits the CSR to Samsung during onboarding process.
Samsung’s PKI signs and returns the client certificate.
Partner installs the signed certificate in the HTTP client. This HTTP client is in their server and uses to call /registrations API.
Separate certificates are issued for staging and production – A single certificate must not be used for both.
Outbound (S2P ➡️ Partner)
Partner has their own CA – an existing internal CA is sufficient, and does not need to be a publicly trusted CA.
Partner issues a client certificate by that CA
Partner delivers the certificate (and the CA’s public root, if not already trusted) to Samsung.
Samsung configures S2P to present this certificate when calling the partner’s /notifications endpoint.
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)
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.
WarningNever mix environments — a staging cert or partner-id must never be used with a production URL, or vice versa.
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
InfoThese headers identify and trace a request, but they do not authenticate the server-to-server communication. Authentication is entirely handled by the mTLS certificate.
Manage Your Cookies
We use cookies to improve your experience on our website and to show you relevant
advertising. Manage you settings for our cookies below.
Essential Cookies
These cookies are essential as they enable you to move around the website. This
category cannot be disabled.
Company
Domain
Samsung Electronics
developer.samsung.com, .samsung.com
Analytical/Performance Cookies
These cookies collect information about how you use our website. for example which
pages you visit most often. All information these cookies collect is used to improve
how the website works.
Company
Domain
Samsung Electronics
.samsung.com
Functionality Cookies
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and
tailor the website to provide enhanced features and content for you.
Company
Domain
Samsung Electronics
developer.samsung.com, google.account.samsung.com
Preferences Submitted
You have successfully updated your cookie preferences.