API References

Inbound APIs (Partner ➡️ S2P)

These are the APIs the partner server must call to integrate with S2P. All requests must be secured with Mutual SSL and must include the partner-id issued to the partner during onboarding.

Base URLs:

  • STG: https://s2p-api.stg.mpay.samsung.com/ext/v1
  • PRD: https://s2p-api.mpay.samsung.com/ext/v1

POST /registrations

Registers a new cardholder/member for the partner program.

Headers

Field

Validation

Description

Content-Type

Required

application/json

partner-id

Required

UUID identifying the partner, issued by Samsung during onboarding

request-id

Required

Unique identifier for this request, used for tracing/troubleshooting

Request Body

Field

Type

Validation

Description

custom.cardArtUrl

String(URL)

Required

URL to the card art image

custom.cardName

String

Required

Name to display on the card

custom.partnerLogoUrl

String(URL)

Required

URL to the partner’s logo image

custom.partnerName

String

Required

Display name of the partner

Example Request

POST /registrations
Content-Type: application/json
partner-id: 550e8400-e29b-41d4-a716-446655440000
request-id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
{
  "custom": {
    "cardArtUrl": "https://partnersite.com/images/cardart.png",
    "cardName": "Jane Doe",
    "partnerLogoUrl": "https://partnersite.com/images/logo.png",
    "partnerName": "Samsung"
  }
}

Response – 201 Created

Field

Validation

Description

id

String

Unique identifier of the newly created registration

welcomeUrl

String(URL)

URL to redirect/send the registrant to, to continue onboarding (S2P welcome flow). Contains an encrypted, time-limited token

welcomeUrlExpiration

Number(epoch milliseconds)

Timestamp at which welcomeUrl expires and can no longer be used

status

String

Registration status.One of:PENDING (initial state, always returned on creation)LINKED

Example Response

HTTP/1.1 201 Created
Content-Type: application/json
{  
  "id": "8f14e45f-ea27-4a2b-9d5c-1a2b3c4d5e6f",  
  "welcomeUrl": "https://s2p.example.com/v1/welcome/eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIn0...",  
  "welcomeUrlExpiration": 1770300000000,  
  "status": "PENDING"
}

Error Responses

HTTP Status

Error Code

Reason

400

400.1

Missing required header, the following parameter/s were not sentpartner-idrequest-id

400

Invalid header valuepartner-id does not match a known/active partner

400

400.1

Invalid request bodyRequired custom field is missing/blankThe JSON has typographical errorsOptional URL field is not a valid URL

400

Invalid stateRegistration was saved, but an internal error occurred while generating the response

415

Content-Type header is missing or not application/json

500

Unexpected internal error

503

Backing datastore temporarily unavailable — safe to retry

GET /registrations/{regId}

Retrieves a registration and issues a new welcome URL for it.

Headers

Field

Validation

Description

partner-id

Required

UUID identifying the partner, issued by Samsung during onboarding

request-id

Required

Unique identifier for this request, used for tracing/troubleshooting

Path Parameters

Field

Type

Validation

Description

regId

String

Required

Identifier of the registration, returned as id from POST /registrations

Example Request

GET /registrations/8f14e45f-ea27-4a2b-9d5c-1a2b3c4d5e6f
partner-id: 550e8400-e29b-41d4-a716-446655440000
request-id: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Response – 200 OK

Field

Validation

Description

id

String

Unique identifier of the registration

welcomeUrl

String(URL)

URL to redirect/send the registrant to, to continue onboarding (S2P welcome flow). Contains an encrypted, time-limited token

welcomeUrlExpiration

Number(epoch milliseconds)

Timestamp at which welcomeUrl expires and can no longer be used

status

String

Registration status.One of:PENDING (initial state, always returned on creation)LINKED

Example Response

HTTP/1.1 201 Created
Content-Type: application/json
{  
  "id": "8f14e45f-ea27-4a2b-9d5c-1a2b3c4d5e6f",  
  "welcomeUrl": "https://s2p.example.com/v1/welcome/eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIn0...", 
  "welcomeUrlExpiration": 1770300000000,  
  "status": "PENDING"
}

Error Responses

HTTP Status

Error Code

Reason

400

400.1

Missing required header, the following parameter/s were not sentpartner-idrequest-id

400

Invalid header valuepartner-id does not match a known/active partner

410

Gone – no registration exists for the given regId

500

Unexpected internal error

503

Backing datastore temporarily unavailable — safe to retry

Outbound Notifications (S2P ➡️ Partner)

This is the API the partner must build and host. S2P calls this endpoint on the partner’s server to notify about provisioning events and to request encrypted card data during provisioning.

Base URL: Provided by the partner during onboarding (staging and production URLs configured separately).

Path: POST /notifications - path is agreed with the partner during onboarding; adjust to match what was registered

Security: Mutual SSL required. S2P connects using a client certificate signed by the partner's own CA — the partner must issue this certificate to Samsung and be able to validate it on inbound connections.

Headers Sent by S2P

Field

Validation

Description

Content-Type

Required

application/json

Accept

Required

Application/json

partner-id

Required

Partner’s S2P-assigned identifier

request-id

Required

Unique identifier for this notification attempt

Request Body

Sent by S2P to the partner’s endpoint

Field

Type

Validation

Description

event.regId

UUID

Required

Registration ID this event relates to

event.type

Enum

Required

One of:WA_READYWA_PROVISIONEDWA_PROVISION_FAILURE

event.error

String

Conditional

Present on failure events. Only CARD_ALREADY_PRESENT is recognized as a specific error today; any other value is treated as a generic failure

user.id

String

Conditional

Samsung account ID. Present for Payment-type cards

emailMatches

Boolean

Optional

If the registration's email matches the Samsung account email

phoneMatches

Boolean

Optional

If the registration’s phone matches the device phone number

device.id

String

Conditional

Device ID. Present for Payment-type cards

wallet.id

String

Conditional

Wallet ID. Present for Payment-type cards

Example Request

POST /notifications
Content-Type: application/json
partner-id: 550e8400-e29b-41d4-a716-446655440000
request-id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
{  
  "event": {    
    "regId": "8f14e45f-ea27-4a2b-9d5c-1a2b3c4d5e6f",    
    "type": "WA_READY"  
  },  
  "user": {    
    "id": "RcSm3gWJT9mXgFWy5sG123"
  },  
  "wallet": {    
    "id": "GpcCUgejS9GIiH8zch1111"  
  },  
  "device": {    
    "id": "MTUxMTE5MDAwMjAwMDM1N999"  
  }
}

Event Types

Type

Error

Delivery

Description

WA_READY

Synchronous – S2P blocks the wallet’s in-progress request waiting on the partner's response

The user has scanned the QR code and linked their Samsung Wallet app to the registration. The partner is expected to pre-provision the card with the issuer and return the encrypted card data (card.data.encryptedData) in the response.

WA_PROVISIONED

Asynchronous, best-effort

The card/token was successfully added to the wallet

WA_PROVISION_FAILURE

Asynchronous, best-effort

Provisioning failed for an unknown reason

WA_PROVISION_FAILURE

CARD_ALREADY_PRESENT

Asynchronous, best-effort

Provisioning failed because the card is already present in the wallet

Response – 200 OK

Field

Type

Validation

Description

card.data.encryptedData

String

Conditional

Encrypted PAN/card data (issuer blob) to provision the card. Required for WA_READY notifications on Payment-type cards — S2P will fail the in-progress provisioning flow if this isn't returned. Not required for WA_PROVISIONED/WA_PROVISION_FAILURE (response body is ignored for these; only the HTTP status matters)

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
{  
  "card": {    
    "data": {      
      "encryptedData": "*****"   
    }  
  }
}