Save To Pay
3 4 save to pay 3 4 1 overview save to pay s2p is a secure integration service by samsung pay that enables partners to store and access user payment credentials for future transactions the communication between the partner’s backend and the save to pay server is protected by mutual ssl two-way ssl authentication, ensuring that both the client and server validate each other's identities key highlights uses a custom certificate authority ca managed by samsung pay techops requires ip allowlisting for both staging and production environments communication is secured over tls 1 2 involves both inbound partner → s2p and outbound s2p → partner api communications, secured via ssl and authenticated with client certificates and headers 3 4 2 endpoints there are 2 endpoints available - staging & production staging will be used for development and integration testing access to these endpoints is restricted to allowlisted ip addresses partner should provide the external ip addresses during the onboarding process supported protocols - tlsv1 2 staging https //s2p-api stg mpay samsung com production https //s2p-api mpay samsung com 3 4 3 onboarding steps to begin integration, follow these onboarding steps step 1 submit a certificate signing request csr partners must generate and send a csr to samsung, along with the following details common name cn for the client certificate partner server base url for receiving outbound notifications from the s2p server external ip address to be added to the access allowlist step 2 receive certificate and partner id samsung will sign the csr using its internal ca and return the client certificate a unique partner id will be issued for each environment this partner id must be included in the headers of every request made to the s2p server 3 4 4 authentication overview mutual ssl is used for both inbound and outbound communication between the partner and the save to pay system inbound partner → save to pay server all requests must be secured with mutual ssl partners connect using the client certificate issued by samsung every request must include the partner id in the header partner ids are environment-specific different for staging and production outbound save to pay server → partner s2p communicates with partner servers over mutual ssl samsung will use a client certificate signed by the partner’s ca partner must be able to validate s2p’s certificate for inbound requests 3 4 5 security protocols protocol tls v1 2 authentication mutual ssl two-way tls certificates partner-to-s2p samsung issues the client certificate s2p-to-partner partner issues the client certificate to samsung 3 4 6 best practices the best practices are keep your client certificate secure and monitor expiration dates log and monitor all inbound/outbound requests for verification and debugging maintain a staging environment for ongoing testing 3 4 7 external api specification the external api specification in the context of samsung's save to pay s2p service refers to the structured guidelines and protocols that define how external partner systems can securely interact with the s2p platform this specification encompasses authentication methods, data formats, api endpoints, and integration workflows to ensure seamless and secure provisioning of payment cards into the samsung wallet app 3 4 8 integration workflow the integration involves several key steps initialization & ui setup step 1–2 register session the partner server initiates the flow by registering with the s2p server on success, it receives regid a unique session identifier must be cached for session tracking welcomeurl a hosted ui url that guides the user through the card addition process step 3 display welcome ui the partner's frontend embeds the welcomeurl ui typically in an <iframe> the ui shows a qr code and clear instructions for the user to continue user interaction step 4 user launches samsung wallet spay wa the user opens the samsung wallet app and scans the qr code shown on the welcome ui if the app is not installed, the ui directs the user to download the samsung wallet app sign in with their samsung account session linking & device validation step 5–6 initiate request & device association spay wa scans the qr code and triggers an initiate request to the s2p server s2p validates the payload and links the device info with the regid the server also forwards the device metadata to the partner server device id wallet id user id the welcome ui updates to show that linking was successful card pre-provisioning step 7–8 partner pre-provisions card the partner server contacts the issuer to pre-provision the card retrieve the encrypted issuerblob which contains secure card/token information step 9 return issuerblob the partner server includes the issuerblob in its notify response back to the s2p server this blob is encrypted only the issuer can decrypt it is device- and wallet-specific only usable by the original device format depends on the issuer step 10 deliver to device the s2p server includes the issuerblob and any other metadata in the initiate response back to the spay wa tokenization steps 11–16 add token in samsung pay spay wa initiates the standard tokenization process using the issuerblob the token is securely added to the samsung wallet for use in nfc or online transactions completion & confirmation step 17 notify s2p server after successful provisioning, spay wa notifies the s2p server that the card/token was added successfully for the given regid step 18 notify partner the s2p server sends a final callback to the partner server confirming the process is completed for the regid 3 4 9 data types type json type format description string string size 2048 boolean boolean object object enum string pattern [a-za-z0-9_]{1,256 values from a limited set are only allowed each field of type enum will define the values allowed phonenumber string pattern [0-9+ -]+ uuid string pattern [a-za-z0-9-_]{26,128} unique identifier url string size 2048 must be an absolute url defined by rfc 2396 uniform resource identifiers uri generic syntax supported schemes - http, https timestamp number int64 - signed 64 bits unix epoch time in milliseconds countrycode string size 2 unique identifier 3 4 10 inbound api specification – save2pay the inbound api specification for save2pay defines the protocols and requirements for partner servers to interact with the save2pay system this specification ensures secure and standardized communication during the push provisioning process general contract base url https //s2p-api mpay samsung com/ext/v1 security mutual ssl is required common headers header name type validation description request-id uuid required unique identifier for the request partner-id uuid required unique identifier that is provided to partner during onboarding partner-id uuid required request-id echoed back in the response headers common http error codes http code description application code message 400 bad request 400 1 invalid data 500 internal server error 500 1 internal server error 503 service not available 503 1 service temporarily unavailable retry-after header is required 503 service not available 503 2 api temporarily unavailable retry-after header is required 3 4 11 registration partner server registers a session for the user as a result, a unique registration id will be generated partner server should make sure that this is called only once for one card a welcomeurl will also be returned partner server can display the welcomeurl in browser or email upon rendering, a qr code will be displayed and users can use their spay wa to scan the qr code welcomeurl has an expiration date, partner server should check if it's still valid before rendering if it's expired, a get call will return the new url request post /registrations body key type validation description example registration email string optional user email address registration enforceemailmatching boolean default is false optional enforce only spay wa with the same email address can provision enforcement is only against the email address that's provided by the partner true registration hideemail boolean default is false optional hide email field registration phone phonenumber optional user phone number registration enforcephonematching boolean optional default is false enforce only spay wa with the same phone number can provision enforcement is only against the phone number that's provided by the partner true registration hidephone boolean optional default is false hide phone field registration welcomecallbackurl url optional callback url that the welcome ui will redirect to once the user successfully linked a spay wa account registration allowofflinecommunication boolean optional default is false if true, s2p will communicate to the user via email and/or phone number to facilitate the provisioning process registration data object optional arbitrary data blob that'll be passed to the device when an account is linked registration custom cardname string required card name that'll show on the welcome page registration custom cardarturl url required cardart url that'll show on the welcome page registration custom partnername string required partner name that'll show on the welcome page registration custom partnerlogourl url required partner logo url that'll show on the welcome page registration custom partnertncurl url optional partner tnc url that'll show on the welcome page registration id uuid required registration id that identifies this session registration status enum - pending, linked required registration status pending registration welcomeurlexpiration timestamp required welcomeurl expiration timestamp in milliseconds response status http/1 1 201 created header name value content-type application/json example post /ext/v1/registrations { "email" "user@gmail com", "enforceemailmatching" true, "phone" "14089998888", "enforcephonematching" true, "custom" { "cardname" "xyz bank credit card", "cardarturl" "https //xyz com/cardart png", "partnername" "xyz bank", "partnerlogourl" "https //xyz com/logo png" } } http/1 1 201 created { "id" "395ce2e29485442cbd9bacdc77105126", "welcomeurl" "https //s2p stg mpay samsung com/v1/welcome/eyjlbmmioijbmju2r0nniiw iywxnijoizglyin0 s0dnxrskdkjw8sbh kg4uqhfwkkdnqrviihkaqshq_jayb99ct tizdzrwrn-qlhuzj4imuyv1sagehavyxluamarwa tlekqcerr0jklc-fnqkcva", "status" "pending", "welcomeurlexpiration" 1505953396844 } get registration check existing registration status and/or get new welcomeurl request get /registrations/{regid} headers name value validation partner-id partner id value assigned by samsung wallet required response status http/1 1 200 ok status name value content-type application/json body key type validation description example registration id uuid required registration id that identify this session registration status enum - pending, linked required registration status pending registration welcomeurl url required this is the url that partner can show to the user as an iframe a separate page it shows the qrcode and optionally user can enter email and phone number registration welcomeurlexpiration timestamp required welcomeurl expiration timestamp in milliseconds example http/1 1 200 ok { "id" "395ce2e29485442cbd9bacdc77105126", "welcomeurl" "https //s2p stg mpay samsung com/v1/welcome/eyjlbmmioijbmju2r0nniiw iywxnijoizglyin0 s0dnxrskdkjw8sbh kg4uqhfwkkdnqrviihkaqshq_jayb99ct tizdzrwrn-qlhuzj4imuyv1sagehavyxluamarwa tlekqcerr0jklc-fnqkcva", "status" "pending", "welcomeurlexpiration" 1505953396844 } errors common http error codes http code description application code message 400 bad request 400 1 invalid data 500 internal server error 500 1 internal server error 503 service not available 503 1 service temporarily unavailable retry-after header is required 503 service not available 503 2 api temporarily unavailable retry-after header is required 3 4 12 outbound to partner the outbound api specification for save2pay defines how the save2pay server communicates with partner servers during the push provisioning process this specification ensures secure and standardized communication between save2pay and its partners general contract base url base url for outbound apis to be provided by the partner during the onboarding process security mutual ssl is required common headers header name type validation description request-id uuid required unique identifier for the request partner-id uuid required unique identifier that is provided to partner during onboarding response-id uuid required request-id echoed back in the response headers 3 4 13 event notification notify partner for events request post /notifications body key description type validation example event regid registration id uuid required event type event type enum refer to event types and errors for details required event error more information about the failure enum refer to event types and errors for details event desc additional description of the event string optional user container for user information object conditional will be present for payment cards user id samsung account id string required emailmatches is true if the email provided in the registration request matches with samsung account email boolean conditional it is present only if an email was provided in the registration request phonematches is true if the phone number provided in the registration request matches with device phone number boolean conditional it is present only if a phone number was provided in the registration request device container for device information object conditional will be present for payment cards device id device id string required device imeilast4 last 4 of device imei string size 4 optional device seriallast4 last 4 of device serial number string size 4 optional device locale country device country code countrycode optional wallet container for wallet information object conditional will be present for payment cards wallet id wallet id string required event types and errors type error description wa_ready wallet app is ready for provisioning wa_provisioned indicates card was successfully provisioned into the wallet wa_provision_failure indicates provisioning failed for some unknown reason wa_provision_failure card_already_present indicates card is already present response status http/1 1 200 ok header name value content-type application/json body card data encrypteddata description encrypted pan data that will be returned to the device to provision the card type string size 65536 validation conditional required if card data was not provided in the registration request example example post /notifications { "event" { "regid" "395ce2e29485442cbd9bacdc77105126", "type" "wa_ready" }, "emailmatches" true, "phonematches" true, "user" { "id" "rcsm3gwjt9mxgfwy5sg123" }, "wallet" { "id" "gpccugejs9giih8zch1111" }, "device" { "id" "mtuxmte5mdawmjawmdm1n999", "imeilast4" "6166", "locale" { "country" "us" }, "seriallast4" "4934" } } http/1 1 200 ok { "card" { "data" { "encrypteddata" "*****" } } } 3 4 14 save to pay javascript library javascript library interface savetopayui { /** * shows the welcome ui redirects to welcomecallbackurl if it was provided in the registration request when the page reaches one of the final states */ static void showwelcomemodal s2prequest r ; /** * shows the welcome ui resolves the promise with the status and optionally details after the welcome ui is closed */ static promise <s2presponse> showwelcomemodalpromise s2prequest r ; /** * api to close the modal */ static void closewelcomemodal ; }; dictionary s2prequest { /** * welcomeurl provided by save2pay server in the registration response */ required domstring welcomeurl; }; dictionary s2presponse { required status status, /** * true if triggered by iframe closing by user or parent page * false if the status is one of the final statuses, not triggered by iframe closing this can only happen in mobile android case */ required boolean isiframeclosed, /** * optional error information if the status is 'failure' */ details details }; dictionary details { required errorcode errorcode; domstring message; }; enum status { "success", "failure", "device_not_supported", "default_pending" }; enum errorcode { "invalid_input", "provision_failure", "network_error", "unknown_error", "card_already_present", "canceled" }; usage code block -1 html <script src="https //spay samsung com/s2p/libs/js/0 0 4/s2p min js"></script> code block -2 javascript - redirect var input = { "welcomeurl" 'https //s2p mpay samsung com/v1/welcome/eyjlbmmioijbmju2r0nniiwiywx nijoizglyin0 eltgw8qp56ciezo2 mh34gjebgyp_m7- gw0sbdl3ckaplp7rtvmc8fe-tmq2ipmp2rcc1a39qodbvw2schiarbooahbe77lpvl8nhkkapi6mhynl-yz6gqx0sjw xfrtyjpdzxrnmlq8ffe6pg' } window spay savetopayui showwelcomemodal input code block- 3 javascript - promise var request = { "welcomeurl" 'https //s2p mpay samsung com/v1/welcome/eyjlbmmioijbmju2r0nniiwiywx nijoizglyin0 eltgw8qp56ciezo2 mh34gjebgyp_m7- gw0sbdl3ckaplp7rtvmc8fe-tmq2ipmp2rcc1a39qodbvw2schiarbooahbe77lpvl8nhkkapi6mhynl-yz6gqx0sjw xfrtyjpdzxrnmlq8ffe6pg' } function successcallback response { console log response status } function failurecallback error { console log error } window spay savetopayui showwelcomemodalpromise request then succes scallback, failurecallback promise resolution device type description desktop, tablet & mobile - ios js library will resolve the promise - 1 when the iframe is closed by the user 2 closewelcomemodal function is invoked mobile - android js library will resolve the promise as soon as the provisioning session ends or closewelcomemodal function is invoked provisioning session ends when one of the following has happened - 1 the card was successfully added 2 there was some failure and card provisioning flow cannot continue further 3 timeout has happened 4 user canceled the provisioning process mobile flows