INBOUND

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)

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

registration.email
Description User email address
Type String
Validation Optional
Example
registration.enforceEmailMatching
Description Enforce only SPay WA with the same email address can provision. Enforcement is only against the email address that's provided by the partner.
Type Boolean. Default is false.
Validation Optional
Example true
registration.hideEmail
Description Hide email field
Type Boolean. Default is false
Validation Optional
Example
registration.phone
Description User phone number
Type PhoneNumber
Validation Optional
Example
registration.enforcePhoneMatching
Description Enforce only SPay WA with the same phone number can provision. Enforcement is only against the phone number that's provided by the partner.
Type Boolean
Validation Optional. Default is false
Example true
registration.hidePhone
Description Hide phone field
Type Boolean
Validation Optional. Default is false
Example
registration.welcomeCallbackUrl
Description Callback URL that the Welcome UI will redirect to once the user successfully linked a SPay WA account
Type URL
Validation Optional
Example
registration.allowOfflineCommunication
Description If true, S2P will communicate to the user via email and/or phone number to facilitate the provisioning process
Type Boolean
Validation Optional. Default is false.
Example
registration.data
Description Arbitrary data blob that'll be passed to the device when an account is linked.
Type Object
Validation Optional
Example
registration.custom.cardName
Description Card name that'll show on the welcome page.
Type String
Validation Required
Example
registration.custom.cardArtUrl
Description CardArt URL that'll show on the welcome page
Type URL
Validation Required
Example
registration.custom.partnerName
Description Partner name that'll show on the welcome page.
Type String
Validation Required
Example
registration.custom.partnerLogoUrl
Description Partner Logo URL that'll show on the welcome page.
Type URL
Validation Required
Example
registration.custom.partnerTncUrl
Description Partner TnC URL that'll show on the welcome page.
Type URL
Validation Optional
Example

Response

Status

HTTP/1.1 201 Created

Header

Name Value
Content-Type application/json

Body

registration.id
Description Registration ID that identify this session
Type UUID
Validation Required
Example
registration.status
Description Registration status
Type Enum - PENDING, LINKED
Validation Required
Example PENDING
registration.welcomeUrl
Description 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
Type URL
Validation Required
Example
registration.welcomeUrlExpiration
Description WelcomeUrl expiration timestamp in milliseconds
Type Timestamp
Validation Required
Example

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

registration.id
Description Registration ID that identify this session
Type UUID
Validation Required
Example
registration.status
Description Registration status
Type Enum - PENDING, LINKED
Validation Required
Example PENDING
registration.welcomeUrl
Description 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.
Type URL
Validation Required
Example
registration.welcomeUrlExpiration
Description WelcomeUrl expiration timestamp in milliseconds
Type Timestamp
Validation Required
Example

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)