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) |