Inbound REST APIs

The inbound REST APIs let you create a Save to Pay card provisioning session and check its registration status.

Use the following base URLs for sending API requests:

• Testing/staging environment: https://s2p-api.stg.mpay.samsung.com/ext/v1
• Production environment: https://s2p-api.mpay.samsung.com/ext/v1

Register a session

Creates a new card provisioning session and, if successful, returns the 201 Created status code along with the registration session ID and the resources needed to display the welcome UI.

Endpoint

POST /registrations

Request parameters

Parameter	Name	Type	Required/Optional	Description
Header	Request-Id	String	Required	Unique request ID.
Header	Partner-Id	String	Required	Unique partner ID, provided by Samsung during onboarding.

Request body (JSON)

Field	Type	Required/Optional	Description
registration.email	String	Optional	Customer's email address.
registration.enforceEmailMatching	Boolean	Optional	Whether card provisioning is allowed only when the email address provided in the request matches the email address associated with the Samsung Wallet account used to scan the QR code. If this field is provided, the registration.email field must also be provided. The default value is false.
registration.hideEmail	Boolean	Optional	Whether the Email field must be hidden on the welcome UI. The default value is false.
registration.phone	String	Optional	Customer's phone number. The value can include digits (0–9), plus signs (+), parentheses (()), hyphens (-), and spaces.
registration.enforcePhoneMatching	Boolean	Optional	Whether card provisioning is allowed only when the phone number provided in the request matches the phone number associated with the Samsung Wallet account used to scan the QR code. If this field is provided, the registration.phone field must also be provided. The default value is false.
registration.hidePhone	Boolean	Optional	Whether the Phone number field must be hidden on the welcome UI. The default value is false.
registration.welcomeCallbackUrl	String	Optional	URL for the issuer website to which the welcome UI redirects when it reaches a final state.
registration.allowOfflineCommunication	Boolean	Optional	Whether Samsung sends a link to the customer via email or SMS. The customer can use the link, instead of the welcome UI, to start the provisioning process. If this field is provided, the registration.email or registration.phone field must also be provided. The default value is false.
registration.data	Object	Optional	Arbitrary data that is passed unchanged to the device when the account is linked.
registration.custom.cardName	String	Required	Card name displayed on the welcome UI.
registration.custom.cardArtUrl	String	Required	URL of your card image displayed on the welcome UI.
registration.custom.partnerName	String	Required	Company name displayed on the welcome UI.
registration.custom.partnerLogoUrl	String	Required	URL of your company logo displayed on the welcome UI.
registration.custom.partnerTncUrl	String	Optional	URL of your terms and conditions page. A link to this page is displayed on the welcome UI.

Response codes

Code	Type	Application code	Message
201	Created		Response body
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
503	Service Not Available	503.2	API Temporarily Unavailable

Response header

Name	Type	Required/Optional	Description
Response-Id	String	Required	Unique response ID that echoes back the Request-Id header from the request.
Retry-After	String	Optional	Delay after which the temporary error is over, and the request can be sent again. Applies only for 503 Service Not Available responses.

Response body for the 201 Created code (JSON)

Field	Type	Description
registration.id	String	Unique registration session ID.
registration.status	Enum	Status for the registration session. The possible values are: PENDING LINKED
registration.welcomeUrl	String	URL for the welcome UI to be displayed on your website. When rendered, it displays a QR code that the customer can scan with their Samsung Wallet app.
registration.welcomeUrlExpiration	Number	Expiration time of the welcome UI's URL, expressed as a Unix epoch timestamp in milliseconds.

Example

Request:

{
    "registration": {
        "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"
        }
    }
}

201 Created response:

{
    "registration": {
        "id": "395ce2e29485442cbd9bacdc77105126",
        "welcomeUrl": "https://s2p.stg.mpay.samsung.com/v1/welcome/eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..S0dNxrskDKjw8SbH.kG4UQhfwKkDNqrvIihkAqShq_JAYb99ctTiZdZrwRN-qLhuZj4iMUYv1SAGEHAVYxlUAmaRWA.TlEKqcErR0jklC-fNQKcVA",
        "status": "PENDING",
        "welcomeUrlExpiration": 1505953396844
    }
}

Retrieve registration status

Retrieves the status of an existing card provisioning session and, if successful, returns the 200 OK status code along with the URL for the latest welcome UI and its expiration information.

Endpoint

GET /registrations/{regId}

Request parameters

Parameter	Name	Type	Required/Optional	Description
Header	Partner-Id	String	Required	Unique partner ID, provided by Samsung during onboarding.
Path	regId	String	Required	Unique ID for the registration session whose details are to be retrieved.

Response codes

Code	Type	Application code	Message
200	OK		Response body
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
503	Service Not Available	503.2	API Temporarily Unavailable

Response header

Name	Type	Required/Optional	Description
Retry-After	String	Optional	Delay after which the temporary error is over, and the request can be sent again. Applies only for 503 Service Not Available responses.

Response body for the 200 OK code (JSON)

Field	Type	Description
registration.id	String	Unique registration session ID.
registration.status	Enum	Status for the registration session. The possible values are: PENDING LINKED
registration.welcomeUrl	String	URL for the welcome UI to be displayed on your website. When rendered, it displays a QR code that the customer can scan with their Samsung Wallet app.
registration.welcomeUrlExpiration	Number	Expiration time of the welcome UI's URL, expressed as a Unix epoch timestamp in milliseconds.

Example

200 OK response:

{
    "registration": {
        "id": "395ce2e29485442cbd9bacdc77105126",
        "welcomeUrl": "https://s2p.stg.mpay.samsung.com/v1/welcome/eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..S0dNxrskDKjw8SbH.kG4UQhfwKkDNqrvIihkAqShq_JAYb99ctTiZdZrwRN-qLhuZj4iMUYv1SAGEHAVYxlUAmaRWA.TlEKqcErR0jklC-fNQKcVA",
        "status": "PENDING",
        "welcomeUrlExpiration": 1505953396844
    }
}