PlayPlus (REST)

On this page:

Introduction

Sightline is a payment technology provider who provides gaming and non-gaming payment products.
The Play+ APM (Alternate Payment Method) is provided by Sightline.

Nuvei Environments

Play+ can be used in Nuvei’s Cashier, Checkout, Web SDK, and REST API payment environments.

Purpose

This guide provides steps to integrate the Play+ APM into your payment flows using the REST API payment environment.

Prerequisites and Notes

  • This document assumes that you have completed all account set up prerequisites, and are ready to integrate the Play+ payment method into your payment flow.
  • The Play+ payment method is supported only for US-based customers, and all amounts sent/received are stated in US Dollars (USD).
  • Test credentials and testing procedures should be obtained directly from the APM providers.

Play+ using REST – Flows

The following sections describe “suggested” flows between you and Play+ via the Nuvei REST API.
You are free to adapt these flows in any way.

REST FlowsDescriptionMain Method Used
Check if the customer has an account with the specified APM provider: paymentOption.alternativePaymentMethod.paymentMethod, and retrieve account details, account balance, account limits, enrolled (registered) bank accounts, etc./getAccountDetails
Retrieve a documentUrl
(Direct flow only)		Retrieve a documentUrl by specifying the documentType: "TermsAndConditions", "PrivacyPolicy" or "FAQ".
The documentUrl is used to redirect the customer to display some information, or to request their agreement to some terms and conditions, before being allowed to proceed. 		/getDocumentUrl
Enroll (register/create) an account for the customer with the specified APM provider.
Fund an Account
(Redirect flow only)		Fund the customer’s account / wallet held with the specified APM provider./fundAccount
Deposit / Withdrawal FlowPerform financial transactions for the customer with the APM provider.
For details, see the Financial Transactions topic.
  • /payment
  • /payout
  • /refundTransaction
Play+ APM payment flows interact directly with the APM provider by bypassing Nuvei’s Digital Payments APM Gateway, which differs from Nuvei’s traditional APM flows.

REST Redirect Flows

Account Inquiry (Redirect)


StepDescription
1Get the customer’s Play+ account details:
Call /getAccountDetails – to check if the customer already has a Play+ account.
  • For status: “ERROR” (customer does not have an account) – PROCEED TO (2A).
  • For status: “SUCCESS” and response returns the customer’s account details (customer already has a Play+ account) – PROCEED TO (2B).

Play+ customer accounts are merchant specific. You will not be aware of the existence of customer accounts created by other merchants.
2BDisplay the Play+ account details and balance. (END OF FLOW)

Enroll (Redirect)


StepDescription
2AEnroll the customer:
Call /enrollAccount (Redirect flow) and include the customer’s bank account details etc. to open a Play+ account for the customer.
  • For status: “SUCCESS” and response returns a redirectUrl – PROCEED TO (3A).
  • For status “ERROR” – Try to resolve it in some way. (END OF FLOW)
3ARedirect the customer by providing an IFrame / pop-up / some type of UI interface, and redirect the customer to the redirectUrl, where they will enroll to open a Play+ account.
Wait for a notification from Play+, and then PROCEED TO (4A).
4AGet the customer’s Play+ account details:
Call /getAccountDetails – for the customer’s newly created Play+ account.
  • For status: “SUCCESS” and response returns the customer’s account details – PROCEED TO (5A).
  • For status: “ERROR” (something is wrong with the customer’s Play+ account). (END OF FLOW)
2B / 5ADisplay the Play+ account details and balance. (END OF FLOW)

Fund Account (Redirect)

StepDescription
6Add Funds to the customer’s Play+ Account by providing some sort of “Fund My Account” button for the customer. When the customer clicks this button, it calls the /fundAccount request.
  • For status: “SUCCESS” and response returns a redirectUrl – PROCEED TO (7).
  • For status: “ERROR” – Try to resolve it in some way. (END OF FLOW)
7Redirect the customer by providing an IFrame / pop-up / some type of UI interface, and redirect the customer to the redirectUrl, where they will move funds from a bank account to their Play+ account.
Wait for a notification from Play+, and then – PROCEED TO (8).
8Get the customer’s Play+ account details:
Call /getAccountDetails to show the customer’s Play+ account.
  • For status: “SUCCESS” and response returns the customer’s account details – PROCEED TO (9).
  • For status: “ERROR”, try to resolve it in some way – PROCEED TO (9).
9Display the Play+ account details and balance. (END OF FLOW)

Payment / Payout Flow

StepDescription
10Perform a financial transaction (/payment, /payout, and /refundTransaction).
For details, see the Financial Transactions topic.

REST Direct Flows

Full REST Direct Flows to support Enroll (NewRequest)

StepDescription
DIR-1Get the customer’s Play+ account details:
Call /getAccountDetails to check if the customer already has a Play+ account.
  • For status: “ERROR”, (customer does not have an account) – PROCEED TO (DIR-2A).
  • For status: “SUCCESS” and response returns the customer’s account details, (customer already has a Play+ account) – PROCEED TO (DIR-2E).

Play+ customer accounts are merchant specific. You will not be aware of the existence of customer accounts created by other merchants.
DIR-2AGet the Document URL for the “TermsAndConditions” document:
Call /getDocumentUrl and set documentType parameter to “TermsAndConditions”.
  • For status: “SUCCESS” and response returns a documentUrl – PROCEED TO (DIR-3A).
  • For status: “ERROR”, try to resolve it in some way. (END OF FLOW)
DIR-3ARedirect the customer to the documentUrl by providing an IFrame / pop-up / or some type of UI interface, where the customer can read the “TermsAndConditions”.
Provide a button that the customer can click to “Accept” the “Terms and Conditions”.
  • When customer accepts “Terms and Conditions” – PROCEED TO (DIR-4A).
  • When customer does not accept “Terms and Conditions”. (END OF FLOW)
DIR-4AEnroll (“NewRequest”) the customer:
Call /enrollAccount (Direct flow) with:
  • sessionToken, your credentials, userId from your internal systems.
  • enrollmentAction = “NewRequest”, enrollmentType = “Standard”,
  • governmentIds[].number, and other relevant parameters.
Responses:
Hard Decline – Account Enrollment Failure:
  • For status: “ERROR” and the response returns paymentMethodErrorReason – PROCEED TO (DIR-5B).
Soft Decline – Enrollment Pending (need the customer to answer KBA (knowledge base authentication) Questions:
  • For status: “KBAPENDING”, and the response returned an array of KBA questions: "verificationQuestions" for the customer to answer. PROCEED TO (DIR-5C).
Success – Customer account created:
  • For status “SUCCESS” – Proceed to (6) to Add Funds to the customer’s Play+ Account (see above).
DIR-5BAccount Enrollment Failure – Returned the paymentMethodErrorReason (END OF FLOW)
DIR-5CReceive array of verificationQuestions – PROCEED TO (DIR-6C).
DIR-6CDisplay the verificationQuestions to the customer, by providing an IFrame / pop-up / or some type of UI interface, where the customer can submit their answers back to you.
DIR-7CTry Enroll the customer again using their answers that you collected.
Call /enrollAccount (Direct flow) with:
  • sessionToken, your credentials, userId from your internal systems
  • enrollmentAction = “KbaResponse”, the array of "kbaResponses" from the customer, enrollmentType = “Standard”
  • governmentIds[].number and other relevant parameters.
Responses:
  • For status: “SUCCESS” – PROCEED TO (6) to Add Funds to the customer’s Play+ Account (see above).
  • For status: “ERROR”, try to resolve it in some way. (END OF FLOW).
DIR-2EDisplay the Play+ account details and balance. (END OF FLOW)

Account Inquiry (Direct)

StepDescription
DIR-1Get the customer’s Play+ account details:
Call /getAccountDetails to check if the customer already has a Play+ account.
  • For status: “ERROR”, (customer does not have an account) – PROCEED TO (DIR-2A).
  • For status: “SUCCESS” and response returns the customer’s account details, (customer already has a Play+ account) – PROCEED TO (DIR-2E).

Play+ customer accounts are merchant specific. You will not be aware of the existence of customer accounts created by other merchants.
DIR-2EDisplay the Play+ account details and balance. (END OF FLOW)

Document URL (Direct)

StepDescription
DIR-2AGet the Document URL for the “TermsAndConditions” document:
Call /getDocumentUrl and set documentType parameter to “TermsAndConditions”.
  • For status: “SUCCESS” and response returns a documentUrl – PROCEED TO (DIR-3A).
  • For status: “ERROR”, try to resolve it in some way. (END OF FLOW)
DIR-3ARedirect the customer to the documentUrl by providing an IFrame / pop-up / or some type of UI interface, where the customer can read the “TermsAndConditions”.
Provide a button that the customer can click to “Accept” the “Terms and Conditions”.
  • When customer accepts “Terms and Conditions” – PROCEED TO (DIR-4A).
  • When customer does not accept “Terms and Conditions”. (END OF FLOW)

Enroll (Direct) – (NewRequest)

StepDescription
DIR-4AEnroll (“NewRequest”) the customer:
Call /enrollAccount (Direct flow) with:
  • sessionToken, your credentials, userId from your internal systems.
  • enrollmentAction = “NewRequest”, enrollmentType = “Standard”,
  • governmentIds[].number, and other relevant parameters.
Responses:
Hard Decline – Account Enrollment Failure:
  • For status: “ERROR” and the response returns paymentMethodErrorReason – PROCEED TO (DIR-5B).
Soft Decline – Enrollment Pending (need the customer to answer KBA (knowledge base authentication) Questions:
  • For status: “KBAPENDING”, and the response returned an array of KBA questions: "verificationQuestions" for the customer to answer. PROCEED TO (DIR-5C).
Success – Customer account created:
  • For status “SUCCESS” – Proceed to (6) to Add Funds to the customer’s Play+ Account (see above).
DIR-5BAccount Enrollment Failure – Returned the paymentMethodErrorReason (END OF FLOW)
DIR-5CReceive array of verificationQuestions – PROCEED TO (DIR-6C).
DIR-6CDisplay the verificationQuestions to the customer, by providing an IFrame / pop-up / or some type of UI interface, where the customer can submit their answers back to you.
DIR-7CTry Enroll the customer again using their answers that you collected.
Call /enrollAccount (Direct flow) with:
  • sessionToken, your credentials, userId from your internal systems
  • enrollmentAction = “KbaResponse”, the array of "kbaResponses" from the customer, enrollmentType = “Standard”
  • governmentIds[].number and other relevant parameters.
Responses:
  • For status: “SUCCESS” – PROCEED TO (6) to Add Funds to the customer’s Play+ Account (see above).
  • For status: “ERROR”, try to resolve it in some way. (END OF FLOW).

REST – Play+ Specific Methods

Nuvei supports the following Play+ specific REST API methods:

REST MethodDescriptionREST Flows
/getAccountDetailsCheck if the customer has an account with the specified APM provider: paymentOption.alternativePaymentMethod.paymentMethod, and retrieve account details, account balance, account limits, enrolled (registered) bank accounts, etc.
/getDocumentUrlRetrieve a documentUrl by specifying the documentType: "TermsAndConditions", "PrivacyPolicy", or "FAQ".
The documentUrl is used to redirect the customer to display some information, or to request their agreement to some terms and conditions, before being allowed to proceed. 		Retrieve a documentUrl
Enroll (register/create) an account for the customer with the specified APM provider.
/fundAccountFund the customer’s account / wallet held with the specified APM provider.Fund an Account

/getAccountDetails

This method is called in the following steps of the REST flows:  1, 4A, 8, DIR-1.

This process allows you to send a /getAccountDetails request to the customer’s “wallet” to retrieve their customer’s available balance and bank accounts details.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request.
2Call the /getAccountDetails request using sessionToken, the userId from your internal systems, and all the other relevant parameters.
3Successful response returns:
  • Account details and card balance etc.
  • status: "SUCCESS"
4Failed response returns:
  • Failed validation of the paymentMethod (if not "apmgw_PlayPlus"):
    status: "ERROR"
    reason: "Unsupported payment method"
    errCode: "1076"

  • Failed attempt to retrieve account details and card balance (no response from Play+):
    status: "ERROR"
    reason: "Communication error"
    errCode: "1038"

  • For any other errors (e.g., Failed validation of the Merchant credentials or sessionToken.):
    status: "ERROR"
    reason: "Balance retrieval error"
    errCode: "9091"
Example /getAccountDetails Request
  • paymentOption.alternativePaymentMethod.paymentMethod must be apmgw_PlayPlus.
  • userId is used as the AccountIdentifier.
{
    "sessionToken":"<sessionToken from getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "userId":"E677539C0C54",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_PlayPlus"
        }
    },
    "deviceDetails":{
        "deviceType":"TABLET",
        "deviceName":"iPad",
        "deviceOS":"iOS U",
        "browser":"safari U",
        "ipAddress":"127.0.0.1"
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "phone":"6175551414",
        "zip":"02460",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "email":"john.smith@email.com",
        "county":"Suffolk",
        "language":"en",
        "dateOfBirth":"1970-06-30",
        "identification":"987456982"
    }
}
Example /getAccountDetails SUCCESS Response
  • userId is used as the AccountIdentifier.
  • accountBalance – The available amount in USD in user’s Play+ wallet.
  • externalTransactionId – The PaymentProcessorTransactionId as returned by Play+.
{
    "reason":"",
    "authCode":"2b3de42362bf49ed8f36df3ab2b3c637",
    "clientRequestId":"R4WXUZUZ7",
    "internalRequestId":"17453921",
    "userId":"E677539C0C54",
    "version":"1.0",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":0,
    "sessionToken":"e0de4572-b08f-4f73-8ef4-99cc0aafdf3e",
    "currency":"USD",
    "externalTransactionId":"2b3de42362bf49ed8f36df3ab2b3c637",
    "accountBalance":"1413.5000",
    "status":"SUCCESS"
}
Example /getAccountDetails ERROR Response
  • userId is used as the AccountIdentifier.
  • paymentMethodErrorCode – The ErrorCode for the first error returned by Play+.
  • paymentMethodErrorReason – Concatenated ErrorMessage and FriendlyMessage for the first error returned by Play+, separated by ” | “.
{
    "reason":"Balance retrieval error",
    "clientRequestId":"GYJ54PS53",
    "internalRequestId":"17453901",
    "userId":"E677539C0C",
    "version":"1.0",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":"9091",
    "paymentMethodErrorCode":"536870912",
    "paymentMethodErrorReason":"Request Failed | IM – Invalid Member Number",
    "sessionToken":"2e8af998-4a31-4f2b-88d8-798da1f0a0f0",
    "status":"ERROR"
}

/enrollAccount (Redirect)

This method is called in the following step of the REST flows:  2A.

This process allows you to send a redirect /enrollAccount request, which presents a UI to the customer, in order to create a wallet in Play+. The method returns a redirectUrl to which you must redirect the customer using an appropriate HTML container.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request.
2Call the /enrollAccount request using sessionToken, the userId from your internal systems, "enrollmentAction": "AccountCapture", and all the other relevant parameters.
3Successful response returns:
  • The Play+ response generates a redirectUrl based on the provided userId, userDetails, urlDetails and identityToken received from Play+.
  • status: "SUCCESS"
4Failed response returns:
  • Failed validation of the paymentMethod (if not "apmgw_PlayPlus"):
    status: "ERROR"
    reason: "Unsupported payment method"
    errCode: "1076"
  • Failed validation of the enrollmentAction (if not “AccountCapture”):
    status": "ERROR"
    reason": "Unsupported enrollmentAction type"
    errCode": "9098"
  • Failed attempt to retrieve account details and card balance (no response from Play+):
    status: "ERROR"
    reason: "Communication error"
    errCode: "1038"
  • For any other errors (e.g. Failed validation of the Merchant credentials or sessionToken):
    status: "ERROR"
    reason: "User account operation failed"
    errCode: "9092"
Example /enrollAccount Request (Redirect)
  • paymentOption.alternativePaymentMethod.paymentMethod must be apmgw_PlayPlus.
  • userId is used as the AccountIdentifier.
  • enrollmentAction must be “AccountCapture“.
{
    "sessionToken":"<sessionToken from getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "userId":"E677539C0C54",
    "enrollmentAction":"AccountCapture",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_PlayPlus"
        }
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "phone":"6175551414",
        "zip":"02460",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "email":"john.smith@email.com",
        "county":"Suffolk",
        "language":"en",
        "dateOfBirth":"1970-06-30",
        "identification":"987456982"
    },
    "urlDetails":{
        "notificationUrl":"[The URL to which DMNs are sent]"
    }
}
Example /enrollAccount SUCCESS Response (Redirect)

userId is used as the AccountIdentifier.

{
    "reason":"",
    "redirectUrl":"https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJ1cmwiOiJodHRwczovL2NlYXBzcGFuZXguc2xwdWF0LmNvbS9Ib3N0ZWRGdW5kaW5nIiwiTWVtYmVyTnVtYmVyIjoiRTY3NzUzOUMwQzU0IiwiRmlyc3ROYW1lIjoiSkFWQVkiLCJMYXN0TmFtZSI6Ik1PU1FVRURBIiwiUGhvbmVOdW1iZXIiOiIzMDE4NTcyMTc1IiwiRW1haWwiOiJzZ2t1eS50eml6dEBlYWJlcS5icSIsIkFkZHJlc3MiOiIyMiBBdXRvbWF0aW9uIFN0ci4iLCJDaXR5IjoiQ2hpcHJvdmNpIiwiU3RhdGUiOiJNRCIsIkNvdW50cnkiOiJVUyIsIlBvc3RhbENvZGUiOiIzMjQyMSIsIklkZW50aXR5VG9rZW4iOiJXQUEwQUZrQWRRQnhBRGdBTVFCVUFFa0FlQUJuQURjQVZBQXpBRVFBYUFCaUFETUFid0JuQUVVQU1nQXZBSFFBU2dCRUFHVUFNQUJtQUhjQWJ3QllBR29BS3dCRUFEZ0FSZ0JYQUdvQVZBQm5BRGdBZGdCRUFIZ0FWQUJ6QUVzQVNRQTNBR3dBTlFCSUFDc0FUZ0EwQUhVQVRnQXlBRklBVFFCS0FHNEFjZ0JIQUhvQVVRQjZBSEVBVWdCUEFETUFNd0JqQURrQVV3Qm9BSEFBYlFCd0FESUFiZ0F4QUdnQVVRQm1BRFFBVWdCbUFERUFTUUJwQUZVQU5BQXlBRWNBTWdBNEFESUFTZ0JrQUM4QVdBQk1BRGtBU1FBeEFFZ0Fjd0E1QUU4QVJnQnFBQ3NBWndCVEFDc0FTQUJzQUVNQVZnQTJBRzBBTndCdEFGVUFNZ0F4QUhnQVdRQldBRkFBUndCRkFHUUFTZ0JSQUhFQVFRQlNBR3NBZHdCd0FHVUFNUUIxQUZVQVNBQndBR0lBYndCWEFFc0FkZ0J6QURjQVRRQktBRkVBV0FBNUFHWUFXUUJHQUZNQWJnQnJBQ3NBWWdCb0FGa0FXZ0JKQUZjQWJ3QlVBR3dBZWdBM0FFRUFTd0JTQURJQVNRQllBRllBT0FCR0FDOEFMd0J1QUM4QU13QktBRXNBYUFCekFHRUFaZ0JMQUZvQU5BQm5BSElBTkFCb0FDOEFjQUJvQUdRQVJnQlJBQzhBU0FBd0FITUFWUUJvQUZVQU1nQk9BR2dBWkFBeUFHWUFjUUF3QURjQVNRQTVBRFlBU3dCdkFHd0FOd0JwQUZrQWJBQnVBQzhBYkFCVkFHc0FNd0FyQUdrQWJ3QkNBRGdBYndCTkFGSUFaZ0JUQUdNQU5BQkhBR3dBY0FCb0FFVUFUUUJ6QUZrQVdRQktBRXdBUXdBMUFFRUFlUUF5QUVJQWRBQk1BRUVBTVFCbkFEMEFQUUE9IiwiTWVyY2hhbnRJRCI6IlNhZmVDaGFyZ2VNZXJjaCIsIk1lcmNoYW50QXBwbGljYXRpb24iOiJTQ2gwMSIsIk1lcmNoYW50VHJhbnNhY3Rpb25JRCI6IjQ4OTExIiwiTWVyY2hhbnROYW1lIjoiU2lnaHRsaW5lIFBheW1lbnRzIiwiRE9CIjoiMTk5Mi0wNi0wMiIsIklkVHlwZSI6IjIiLCJJZFZhbHVlIjoiMDUzOTQyNjg0In0.kwFY4mUPP-Xjq29yKCrhVoAmWOsDun0Ryukp-267PEDA52pADABcerd6ifl6JfcGK2ahMnNlOyu8vS-7BVSD8-z3qIvUY446M6K4GZxuCjRPREfx9c3oJwhqpN0vU8YLfiIrf8sHKPKlapxDg0vunjppQRSijqk0hMokRoH6_5Pstm6e7yhH3SFVi_B7Qe569Ny-P1nbC3Ult2h-AbsXAanlKfO1IPGEEbtUaPZatViAmd7TIjYigB02NkOtlAr9l_kpjE0fv2CSMtVGHvy1PkzaMaYO7KCdCagV_jB56dgPoYJYwuVMv3C7FMc1OWaA_cakeSL9LHH795mP3wuXuA",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":0,
    "clientRequestId":"KFK1BUZJ4",
    "sessionToken":"69234cef-8d45-4afc-b44b-18e99f2e8633",
    "internalRequestId":"17455361",
    "userId":"E677539C0C54",
    "version":"1.0",
    "status":"SUCCESS",
    "merchantSiteId":"126006"
}
Example /enrollAccount ERROR Response (Redirect)
  • userId is used as the AccountIdentifier.
  • paymentMethodErrorCode – The ErrorCode for the first error returned by Play+.
  • paymentMethodErrorReason – Concatenated ErrorMessage and FriendlyMessage for the first error returned by Play+, separated by ” | “.
{
    "reason":"User account operation failed",
    "clientRequestId":"OZFE5CLJB",
    "internalRequestId":"17480951",
    "userId":"E677539C0C54",
    "version":"1.0",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":"9092",
    "paymentMethodErrorCode":"536870926",
    "paymentMethodErrorReason":"Access Denied | CERTSAFECHRGEAPI01 is not associated with CERTSAFECHRGE, or CERTSAFECHRGE does not exist.",
    "sessionToken":"40d7a7a2-fc58-4030-b820-9d9f441d1422",
    "status":"ERROR"
}

/getDocumentUrl

This method is called in the following step of the REST flows:  DIR-2A.

This process allows you to request a documentUrl by specifying the documentType: TermsAndConditions, PrivacyPolicy or FAQ in the /getDocumentUrl request.

It supports two modes of operation:

  • anonymous – The document is only reviewed by the customer.
  • registration – The customer must accept the Terms & Conditions document.

This method returns a URL to the document specified in the request, in the Play+ Direct flow.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request.
2Call the /getDocumentUrl request using sessionToken, userId from your internal systems, documentType, and all the other relevant parameters.
3Successful response returns:
  • The Play+ response returns a documentUrl based on the requested documentType.
  • status: "SUCCESS"
4Failed response returns:
  • Failed validation of paymentMethod (if not "apmgw_PlayPlus"):
    status: "ERROR"
    reason: "Unsupported payment method"
    errCode: "1076"
  • Failed validation that documentType is one of these: “TermsAndConditions”, “PrivacyPolicy” or “FAQ”.
    status: "ERROR"
    reason" "Unsupported document type"
    errCode" "9097"
  • For any other errors (e.g. Failed validation of the Merchant credentials or sessionToken):
    status: "ERROR"
    reason: "User account operation failed"
    errCode: "9092"
Example /getDocumentUrl Request – Anonymous (no userId), documentType: “TermsAndConditions”
  • paymentOption.alternativePaymentMethod.paymentMethod must be apmgw_PlayPlus.
  • documentType – Supported values: TermsAndConditions, PrivacyPolicy or FAQ.
  • For userId:
    • This is used as the AccountIdentifier in Play+.
    • Use the same value in /getDocumentUrl and /enrollAccount calls.
    • Not mandatory for an “anonymous” request (which returns a "view-only" documentUrl).

{
    "sessionToken":"<sessionToken from getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_PlayPlus"
        }
    },
    "documentType":"TermsAndConditions"
}
Example /getDocumentUrl Response – Anonymous (no userId), documentType: “TermsAndConditions”

documentUrl – The URL of the specified document hosted on the Play+ server.

{
    "reason":"",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":0,
    "clientRequestId":"HIS79GYC4",
    "documentUrl":"https://ceapspanex.slpuat.com/playplusdocumentviewer/view/document/TCURL/SCh01",
    "sessionToken":"aab1cbec-f9b4-40d6-8f4b-e60e0cfcc3c9",
    "internalRequestId":17743421,
    "version":"1.0",
    "status":"SUCCESS",
    "merchantSiteId":"126006"
}
Example /getDocumentUrl Request – Registration (with userId), documentType: "FAQ"
  • paymentOption.alternativePaymentMethod.paymentMethod must be apmgw_PlayPlus.
  • userId is used the as AccountIdentifier.
  • documentType – Supported values: TermsAndConditions, PrivacyPolicy or FAQ.
{
    "sessionToken":"<sessionToken from getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "userId":"E677539C0C54",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_PlayPlus"
        }
    },
    "documentType":"FAQ"
}
Example /getDocumentUrl Response – Registration (with userId), documentType: " FAQ"
  • userId is used as the AccountIdentifier.
  • documentUrl – The URL of the specified document hosted on the Play+ server.
{
    "reason":"",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":0,
    "clientRequestId":"4LABDBTQ5",
    "documentUrl":"https://ceapspanex.slpuat.com/playplusdocumentviewer/view/document/FAQURL/SCh01/E677539C0C54/SafeChargeMerch/695701003",
    "sessionToken":"7f97c205-f683-4a25-8f2b-717a8769a0b9",
    "internalRequestId":17743711,
    "userId":"E677539C0C54",
    "version":"1.0",
    "status":"SUCCESS",
    "merchantSiteId":"126006"
}

/enrollAccount (Direct)

This method is called in the following steps of the REST flows: DIR-4A / DIR-7C.

This process allows you to send a direct API /enrollAccount request to Play+ for account enrollment.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request.
2Call the /enrollAccount request using sessionToken, userId from your internal systems, and all the other relevant parameters.
  • For (step DIR-4A): enrollmentAction: "NewRequest"
  • For (step DIR-7C): enrollmentAction: "KbaResponse"
3Successful response returns:
  • The Play+ response creates an account for the customer in their system based on the provided userId, userDetails, urlDetails and identityToken received from Play+.
  • status: "SUCCESS"
4Failed response returns:
  • Failed validation of paymentMethod (if not "apmgw_PlayPlus"):
    status: "ERROR"
    reason: "Unsupported payment method"
    errCode: "1076"
  • Failed validation, enrollmentType is not “Standard”:
    status: "ERROR"
    reason: "Unsupported enrollment type"
    errCode: "9099"
  • Failed to retrieve account details and card balance (no response from Play+):
    status: "ERROR"
    reason: "Communication error"
    errCode: "1038"
  • For any other errors (e.g. Failed validation of the Merchant credentials or sessionToken).
  • If there is at least one error and no values for identityVerificationRequestId, identityVerifierRequestId and verificationQuestions, then ERROR is returned with the error information.
  • If there is at least one error and there are values for identityVerificationRequestId, identityVerifierRequestId and verificationQuestions, then “KBAPENDING” is returned with error information:
    status: "ERROR"
    reason: "User account operation failed"
    errCode: "9092"
Example /enrollAccount Request (Direct)(NewRequest)
  • paymentOption.alternativePaymentMethod.paymentMethod must be apmgw_PlayPlus.
  • userId is used as the AccountIdentifier.
  • enrollmentAction is NewRequest.
  • enrollmentType is Standard.
  • phoneNumber[].type – Supported values are: Unknown, Home, Work, Cell.
  • governmentIds[].idType – Supported values are: SSN, DriversLicence, Passport and MilitaryId.
{
    "sessionToken":"<sessionToken from getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "userId":"MD9XJRZZTP6M",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_PlayPlus"
        }
    },
    "enrollmentAction":"NewRequest",
    "enrollmentType":"Standard",
    "governmentIds":[
        {
            "idType":"DriversLicense",
            "issuingGovernment":{
                "country":"US",
                "isState":"True",
                "isCountry":"True",
                "state":"GA"
            },
            "number":"112223333"
        },
        {
            "idType":"SSN",
            "issuingGovernment":{
                "country":"US",
                "isState":"True",
                "isCountry":"True",
                "state":"GA"
            },
            "number":"112223333"
        }
    ],
    "phoneNumbers":[
        {
            "number":"3126122528",
            "type":"Home"
        },
        {
            "number":"3126122548",
            "type":"Work"
        }
    ],
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"john.smith@email.com",
        "phone":"3459873345",
        "address":"22 Main Street",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "zip":"02460",
        "cell":"6175553333",
        "county":"Suffolk",
        "homePhone":"6175551414",
        "workPhone":"6175552222"
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "phone":"6175551414",
        "zip":"02460",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "email":"john.smith@email.com",
        "dateOfBirth":"1975-02-02",
        "identification":"112223333"
    }
}
Example /enrollAccount Response – (Direct)(NewRequest) – SUCCESS
  • userId is used as the AccountIdentifier.
  • status is SUCCESS.
  • paymentMethodErrorCode – The ErrorCode for the first error returned by Play+.
  • paymentMethodErrorReason – Concatenated ErrorMessage and FriendlyMessage for the first error returned by Play+, separated by ” | “.
{
    "reason":"",
    "identityVerificationRequestId":"0",
    "authCode":"70419e03d7844a9c8ee5fdbad9da8ecb",
    "clientRequestId":"A0V7QVWLA",
    "internalRequestId":17762171,
    "userId":"MD9XJRZZTP6M",
    "version":"1.0",
    "merchantSiteId":"126006",
    "identityVerifierRequestId":"",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"7HY2XQWMENHA",
    "errCode":0,
    "sessionToken":"26544891-c629-43b0-ab61-083ae19ee755",
    "externalTransactionId":"70419e03d7844a9c8ee5fdbad9da8ecb",
    "status":"SUCCESS"
}
Example /enrollAccount Response – (Direct)(NewRequest) – Hard Decline

Once a “hard decline” is issued, the enroll process is ended.

  • userId is used as the AccountIdentifier.
  • status is ERROR.
  • paymentMethodErrorCode – The ErrorCode for the first error returned by Play+.
  • paymentMethodErrorReason – Concatenated ErrorMessage and FriendlyMessage for the first error returned by Play+, separated by ” | “.
{
    "reason":"User account operation failed",
    "identityVerificationRequestId":"148696",
    "clientRequestId":"7ZNXH47WO",
    "internalRequestId":17750061,
    "userId":"XRWC7NU58DFR",
    "version":"1.0",
    "merchantSiteId":"126006",
    "verificationQuestions":[
        
    ],
    "merchantId":"2502136204546424962",
    "clientUniqueId":"6SKUJ9I8BDMH",
    "errCode":9092,
    "paymentMethodErrorCode":"536870912",
    "paymentMethodErrorReason":"Request Failed | Id Verification Failure – Hard",
    "sessionToken":"615d1f91-33f0-4f36-9874-5b6c999448a7",
    "status":"ERROR"
}
Example /enrollAccount Response – (Direct)(NewRequest) – Soft Decline

Unlike a “hard decline“, when a “soft decline” is issued, the enroll process continues. A KBA request is sent with the missing information from the original request with which the enrollment process can be successfully completed.

  • userId is used as the AccountIdentifier.
  • status is KBAPENDING.
  • paymentMethodErrorCode – The ErrorCode for the first error returned by Play+.
  • paymentMethodErrorReason – Concatenated ErrorMessage and FriendlyMessage for the first error returned by Play+, separated by ” | “.
{
    "reason":"User account operation failed",
    "identityVerificationRequestId":"148838",
    "clientRequestId":"69OKV8P1L",
    "internalRequestId":17762491,
    "userId":"7T31TNHGLTE7",
    "version":"1.0",
    "merchantSiteId":"126006",
    "identityVerifierRequestId":"3549880445",
    "verificationQuestions":[
        {
            "questionId":"current.county.b",
            "answers":[
                {
                    "value":"MANU'A",
                    "key":"MANU'A"
                },
                {
                    "value":"JALUIT",
                    "key":"JALUIT"
                },
                {
                    "value":"FULTON",
                    "key":"FULTON"
                },
                {
                    "value":"None of the above",
                    "key":"None of the above"
                }
            ],
            "prompt":"In which county have you lived?",
            "questionType":"current.county.b"
        },
        {
            "questionId":"property.size",
            "answers":[
                {
                    "value":"1,000 or less",
                    "key":"1,000 or less"
                },
                {
                    "value":"1,001 - 1,500",
                    "key":"1,001 - 1,500"
                },
                {
                    "value":"1,501 - 2,000",
                    "key":"1,501 - 2,000"
                },
                {
                    "value":"2,001 - 2,500",
                    "key":"2,001 - 2,500"
                },
                {
                    "value":"Over 2,500",
                    "key":"Over 2,500"
                },
                {
                    "value":"None of the above",
                    "key":"None of the above"
                }
            ],
            "prompt":"What is the approximate square footage of the property at 222333 PEACHTREE PLACE?",
            "questionType":"property.size"
        },
        {
            "questionId":"person.known.fic",
            "answers":[
                {
                    "value":"LISA MCKITRICK",
                    "key":"LISA MCKITRICK"
                },
                {
                    "value":"REGINA ROTHENBERG",
                    "key":"REGINA ROTHENBERG"
                },
                {
                    "value":"MANNY EDELSTEIN",
                    "key":"MANNY EDELSTEIN"
                },
                {
                    "value":"None of the above",
                    "key":"None of the above"
                }
            ],
            "prompt":"Which of the following people do you know?",
            "questionType":"person.known.fic"
        },
        {
            "questionId":"city.of.residence",
            "answers":[
                {
                    "value":"CAMP VERDE",
                    "key":"CAMP VERDE"
                },
                {
                    "value":"HILLSIDE",
                    "key":"HILLSIDE"
                },
                {
                    "value":"ALMO",
                    "key":"ALMO"
                },
                {
                    "value":"None of the above",
                    "key":"None of the above"
                }
            ],
            "prompt":"In which city is ANY STREET?",
            "questionType":"city.of.residence"
        }
    ],
    "merchantId":"2502136204546424962",
    "clientUniqueId":"PRKQQ4YFG3YU",
    "errCode":9092,
    "paymentMethodErrorCode":"536870912",
    "paymentMethodErrorReason":"Request Failed | Id Verification Failure – Soft",
    "sessionToken":"c5c62461-fd8d-425c-b914-cc135399e3d9",
    "status":"KBAPENDING"
}
Example /enrollAccount Request – (Direct)(NewRequest) – For KBA Response
  • paymentMethod under paymentOption.alternativePaymentMethod must be apmgw_PlayPlus.
  • userId is used as the AccountIdentifier.
  • enrollmentAction is KbaResponse.
  • enrollmentType is Standard.
  • phoneNumber[].type – Supported values are: Unknown, Home, Work, Cell.
  • governmentIds[].idType – Supported values are: SSN, DriversLicence, Passport and MilitaryId.
  • previousIdentityVerificationRequestId and previousIdentityVerifierRequestId are required for KbaResponse requests.
{
    "sessionToken":"<sessionToken from getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "userId":"7T31TNHGLTE7",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_PlayPlus"
        }
    },
    "enrollmentAction":"KbaResponse",
    "enrollmentType":"Standard",
    "previousIdentityVerificationRequestId":"148838",
    "previousIdentityVerifierRequestId":"3549880445",
    "kbaResponses":[
        {
            "key":"current.county.b",
            "value":"SUFFOLK"
        },
        {
            "key":"property.size",
            "value":"Over 2,500"
        },
        {
            "key":"person.known.fic",
            "value":"None of the above"
        },
        {
            "key":"city.of.residence",
            "value":"BOSTON"
        }
    ],
    "governmentIds":[
        {
            "idType":"SSN",
            "issuingGovernment":{
                "country":"US",
                "isState":"True",
                "isCountry":"True",
                "state":"MA"
            },
            "number":"112223333"
        }
    ],
    "phoneNumbers":[
        {
            "number":"3126122528",
            "type":"Work"
        }
    ],
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"john.smith@email.com",
        "phone":"6175551414",
        "address":"22 Main Street",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "zip":"02460",
        "cell":"6175553333",
        "county":Suffolk,
        "addressMatch":"N",
        "addressLine2":"Billing Address Line 2",
        "addressLine3":"Billing Address Line 3",
        "homePhone":"6175551414",
        "workPhone":"6175552222"
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "phone":"6175553333",
        "zip":"02460",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "email":"john.smith@email.com",
        "county":"Suffolk",
        "language":"en",
        "dateOfBirth": "1970-06-30",
        "identification":"112223333"
    }
}
Example /enrollAccount Response – (Direct)(NewRequest) – For KBA Response

userId is used as the AccountIdentifier.

{
    "reason":"",
    "identityVerificationRequestId":"0",
    "authCode":"6f4e88d31968455fb754f6063bfe5865",
    "clientRequestId":"QSTUVZCT0",
    "internalRequestId":17762541,
    "userId":"7T31TNHGLTE7",
    "version":"1.0",
    "merchantSiteId":"126006",
    "identityVerifierRequestId":"",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"PRKQQ4YFG3YU",
    "errCode":0,
    "sessionToken":"700faa58-671a-4348-acd6-5bb047e81725",
    "externalTransactionId":"6f4e88d31968455fb754f6063bfe5865",
    "status":"SUCCESS"
}

/fundAccount

This method is called in the following step of the REST flows:  6.

This process allows you to send a /fundAccount request, which presents a UI to the customer in order to add funds to their wallet in Play+. The method returns redirectUrl to which you must redirect the customer using an appropriate HTML container.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request.
2Call the /fundAccount request using sessionToken, userId from your internal systems, and all the other relevant parameters.
3Successful response returns:
  • The Play+ response generates a redirectUrl based on the provided userId, userDetails, urlDetails and identityToken received from Play.
  • status: "SUCCESS"
4Failed response returns:
  • Failed validation of paymentMethod (if not "apmgw_PlayPlus"):
    status: "ERROR"
    reason: "Unsupported payment method"
    errCode: "1076"
  • Failed attempt to retrieve account details and card balance (no response from Play+):
    status: "ERROR"
    reason: "Communication error"
    errCode: "1038"
  • For any other errors (e.g. Failed validation of the Merchant credentials or sessionToken):
    status: "ERROR"
    reason: "Cannot fund user account at this time"
    errCode: "9096"
Example /fundAccount Request
  • paymentOption.alternativePaymentMethod.paymentMethod must be apmgw_PlayPlus.
  • userId is used as the AccountIdentifier.
{
    "sessionToken":"<sessionToken from getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "userId":"E677539C0C54",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_PlayPlus"
        }
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "phone":"6175551414",
        "zip":"02460",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "email":"john.smith@email.com",
        "county":"Suffolk",
        "language":"en",
        "dateOfBirth":"1970-06-30",
        "identification":"987456982"
    },
    "urlDetails":{
        "notificationUrl":"[The URL to which DMNs are sent]"
    }
}
Example /fundAccount SUCCESS Response

userId is used as the AccountIdentifier.

{
    "reason":"",
    "redirectUrl":"https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJ1cmwiOiJodHRwczovL2NlYXBzcGFuZXguc2xwdWF0LmNvbS9Ib3N0ZWRGdW5kaW5nIiwiTWVtYmVyTnVtYmVyIjoiRTY3NzUzOUMwQzU0IiwiRmlyc3ROYW1lIjoiSkFWQVkiLCJMYXN0TmFtZSI6Ik1PU1FVRURBIiwiUGhvbmVOdW1iZXIiOiIzMDE4NTcyMTc1IiwiRW1haWwiOiJzZ2t1eS50eml6dEBlYWJlcS5icSIsIkFkZHJlc3MiOiIyMiBBdXRvbWF0aW9uIFN0ci4iLCJDaXR5IjoiQ2hpcHJvdmNpIiwiU3RhdGUiOiJNRCIsIkNvdW50cnkiOiJVUyIsIlBvc3RhbENvZGUiOiIzMjQyMSIsIklkZW50aXR5VG9rZW4iOiJjUUJrQUhjQVdBQnVBRTRBT1FCUkFFOEFRZ0JUQUcwQVJBQTFBR01BU2dCaUFHWUFaQUJsQUZFQVJnQkRBR29BWkFCV0FFb0FPQUJVQUZVQU53Qk9BRU1BTlFCWEFFc0FNd0ExQUhVQU1BQnNBRGdBU3dCakFHTUFaQUJxQUhVQVdBQk9BRVFBV2dCU0FFd0FVZ0JrQURZQWJnQnBBRU1BVVFCTkFIY0FTZ0JNQUZRQWJnQlBBRFVBYWdBMkFIb0FSQUJLQUhnQVVnQmxBRk1BTndCc0FIUUFNQUJvQUdzQWNRQTBBRzBBU3dBM0FIa0FWQUEyQUVFQVpBQlZBREFBU0FCdEFGb0FUQUJMQUVnQVRnQlBBRThBVEFBd0FHWUFMd0JpQUd3QU1BQlJBRElBU1FCQ0FGa0FVUUJuQUZVQVpBQmhBRFVBYkFCMEFHTUFUUUJJQUdRQU1nQlpBSFFBVEFCMEFHb0Fjd0JsQUZvQVl3QXdBSG9BV2dCNUFEUUFhUUJLQUNzQVdnQnZBR2dBZUFBMkFHOEFiZ0I2QUVRQVVRQk1BRGdBVlFCcEFISUFjZ0JUQUdNQWNRQTNBRUlBVGdCREFGQUFUZ0JSQUVZQWN3QkNBRElBTUFCWkFIZ0FVZ0JWQUc0QWNBQnZBRU1BUVFCMEFFRUFXZ0FyQUM4QVZ3QlhBRTRBYlFCb0FFd0FaUUIwQURjQVlnQkNBRVVBTndCeUFGWUFTQUF6QUZFQVNBQkdBR2dBYndCU0FGb0FkUUJUQURjQVVnQTJBRUVBZHdCNkFIVUFNUUJwQURJQWR3QkxBRVFBZHdCNkFHY0FUUUJuQUZNQU1nQmpBR29BT1FCRUFIQUFUd0J5QUZFQVZBQTFBRE1BU1FCckFFRUFkZ0JPQUd3QUt3QjBBRXdBV2dCUEFEQUFaZ0JNQURnQWFnQTNBRUVBYlFCMUFHc0FXUUE0QUVRQWVRQm9BREFBUVFCbkFEMEFQUUE9IiwiTWVyY2hhbnRJRCI6IlNhZmVDaGFyZ2VNZXJjaCIsIk1lcmNoYW50QXBwbGljYXRpb24iOiJTQ2gwMSIsIk1lcmNoYW50VHJhbnNhY3Rpb25JRCI6IjUwMTkxIiwiTWVyY2hhbnROYW1lIjoiU2lnaHRsaW5lIFBheW1lbnRzIiwiRE9CIjoiMTk5Mi0wNi0wMiIsIklkVHlwZSI6IjIiLCJJZFZhbHVlIjoiMDUzOTQyNjg0In0.WPa7Hpq0f-rsr5pDvVOtz3SmFUUZg1c1dHbd9_rf5lXMKpnv23SZsH_RwG1P0uu_5JaLQoE6yyVHJ7Q_l5FX-CzNZlcOYXYwOYagz7PmL9vtdMfN1Ey6p9Z8ANs9mtub8yy-GWOhFH_wvGaN4KGll_rT35MnorBiPEJnix_ZHqI0F42cNuUj9cqVLhbe-furAmWqpa7zhvPQ1MfQ3wCZx57KgM0F4iZ75HBxIYGf3U5XTrTjTrQvEENbMsqvqvWtxFmq240zrsOdHMC8vXJp29t5CdtZEzmeAZAAUNM8I7Mho_Mg-xRHgFsu5WmPp4qHBqds-GNKTYmubCzQocXtPg",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":0,
    "clientRequestId":"O3V96K7EV",
    "sessionToken":"72c9dab5-00b0-4d1b-8b24-a9b5e0a1a795",
    "internalRequestId":"17480361",
    "userId":"E677539C0C54",
    "version":"1.0",
    "status":"SUCCESS",
    "merchantSiteId":"126006"
}
Example /fundAccount ERROR Response
  • userId is used as the AccountIdentifier.
  • paymentMethodErrorCode – The ErrorCode for the first error returned by Play+.
  • paymentMethodErrorReason – Concatenated ErrorMessage and FriendlyMessage for the first error returned by Play+, separated by ” | “.
{
    "reason":"User account operation failed",
    "clientRequestId":"OZFE5CLJB",
    "internalRequestId":"17480951",
    "userId":"E677539C0C54",
    "version":"1.0",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":"9092",
    "paymentMethodErrorCode":"536870926",
    "paymentMethodErrorReason":"Access Denied | CERTSAFECHRGEAPI01 is not associated with CERTSAFECHRGE, or CERTSAFECHRGE does not exist.",
    "sessionToken":"40d7a7a2-fc58-4030-b820-9d9f441d1422",
    "status":"ERROR"
}

REST Financial Transactions

This topic provides details for REST flows:  10.

You can use Nuvei REST API methods to perform the following financial transactions with the Play+ APM payment provider:

  • Payment (deposit) transactions:
    • Payment without UPO – Send a /payment request using the customer’s Play+ account details (no UPO).
    • Payment with an UPO – Send a /payment request using the customer’s existing UPO payment method (which represents the customer’s Play+ account).
  • Payout (withdrawal) transaction – Send a /payout  request.
  • Refund – Send a /refundTransaction request.

Payment without UPO – REST

You can send REST API /payment requests, and include the additional Play+ parameters, as described in the steps below.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request.
2Use /getAccountDetails to retrieve details of the customer’s bank accounts enrolled (registered) in their Play+ account.
3Display these bank accounts to the customer, for them to select a bank account.
4Call the /payment request using sessionToken, userId from your internal systems, and the additional Play+ parameters to include shown below.

  • If the API /payment request is "APPROVED" and there is no pre-existing UPO (userPaymentOptionId) associated with the customer’s Play+ account, then a new UPO record is created using the Play+ account details supplied in the successful /payment request.

  • If the API /payment request is "APPROVED" and there is a pre-existing UPO associated with the customer’s Play+ account, then that record is updated using the Play+ account details supplied in the successful /payment request.

  • If the transaction was not approved and there is a pre-existing UPO associated with the customer’s Play+ account, then that UPO record is not replaced. The existing UPO record remains as it was before sending the API /payment request.
5After processing the transaction, if a urlDetails.notificationUrl parameter was provided in the request, then Nuvei returns a DMN that includes the result of the transaction.
See an example DMN Response below.
Additional Parameters to Include

Include the following additional parameters in the paymentOption.alternativePaymentMethod block, as shown below:

ParameterMandatoryNotes
paymentOption
.alternativePaymentMethod
.paymentMethod		Y"apmgw_PlayPlus"
paymentOption
.alternativePaymentMethod
.sightline_ssn		Y"Last 4 digits of the customer SSN"
This is included in the alternativePaymentMethod, not the “user details”.
userTokenIdConditional(Mandatory - Can use either userTokenId or userId but not both.)
Use userTokenId if you use a UPO. Should contain the same value used for account creation.
userIdConditional(Mandatory - Can use either userTokenId or userId but not both.)
The ID of the customer in the Merchant system.
Use userId if you do not use a UPO.
Should contain the same value used for account creation.
Example /payment Request (without UPO)
{
    "sessionToken":"<sessionToken from getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "userTokenId": "<unique customer identifier in merchant system>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "currency":"USD",
    "amount":"200",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_PlayPlus",
            "sightline_ssn":"2684"
        }
    },
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "cell":"6175553333",
        "phone":"6175551414",
        "zip":"02460",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "email":"john.smith@email.com"
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"john.smith@email.com",
        "phone":"6175551414",
        "cell":"6175553333",
        "dateOfBirth":"1970-06-30",
        "address":"22 Main Street",
        "city":"Boston",
        "zip":"02460",
        "county":"Suffolk",
        "state":"MA",
        "country":"US",
        "language":"en",
        "identification":"053942684"
    },
    "deviceDetails":{
        "deviceType":"DESKTOP",
        "deviceName":"iPhone 5s",
        "deviceOS":"iOS 10.2",
        "browser":"safari",
        "ipAddress":"192.168.2.38"
    },
    "urlDetails":{
        "notificationUrl":"[The URL to which DMNs are sent]"
    },
    "customSiteName":"<CustomSiteName>",
    "productId":"<productId>",
    "customData":"<Custom Data>",
    "webMasterId":"<webMasterId>",
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
Example /payment Response (without UPO)
{
    "reason":"",
    "orderId":"36234231",
    "transactionStatus":"APPROVED",
    "clientRequestId":"2LZ7D1LKJ",
    "internalRequestId":17661281,
    "version":"1.0",
    "transactionId":"2110000000004199287",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"BE4OUD9VR5RG",
    "errCode":0,
    "paymentOption":{
        "userPaymentOptionId":"8042541",
        "card":{
            
        }
    },
    "sessionToken":"e8e32e0c-fef0-41d9-9eb1-72b69d0c27e4",
    "userTokenId":"E677539C0C54",
    "status":"SUCCESS"
}
Example /payment DMN Response (without UPO)
ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=36234231&userid=E677539C0C54&merchant_unique_id=BE4OUD9VR5RG&customData=Custom+Data%21&productId=&first_name=John&last_name=Smith&email=john.smith%40email.com&currency=USD&clientUniqueId=BE4OUD9VR5RG&customField1=customField1-value&customField2=customField2-value&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=22+Automation+Str.+Updated.&address2=&country=United+States&state=&city=Boston+Updated&zip=CH+233242U&phone1=3459873345&phone2=&phone3=&client_ip=192.168.2.38&nameOnCard=&cardNumber=&bin=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&AuthCode=2684&AvsCode=&Cvv2Reply=&shippingCountry=US&shippingState=&shippingCity=Shipping+City+Updated&shippingAddress=33+Shipping+Str.+Updated.&shippingZip=SDC+33334U&shippingFirstName=john&shippingLastName=Uvnoirngbg&shippingPhone=359888576900&shippingCell=359887576903&shippingMail=gmwch.bphmv%40ducdb.qz&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=126006&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_PlayPlus&ID=&merchant_id=2502136204546424962&responseTimeStamp=2021-07-28.11%3A29%3A39&buyButtonProductId=&webMasterId=VB7BKRDSEEDI&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=E677539C0C54&userPaymentOptionId=8042541&TransactionID=2110000000004199287&externalTransactionId=b166096c-6e4f-4437-8efb-ea53da3f5f1e&APMReferenceID=3C2EC9B835DD7CF948E4C894AAD4C12B&orderTransactionId=18075011&totalAmount=10.00&dynamicDescriptor=MerchantNameDescriptor123456789101112131415&item_name_1=Item+1U&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20210709&shippingCounty=SCountyU&type=DEPOSIT&clientRequestId=2LZ7D1LKJ&relatedTransactionId=&responsechecksum=4981a58a05cca78d21e1ad0cb570e9b1&advanceResponseChecksum=b281386292c67407e40d551717898009

Payment with UPO – REST

You can send REST API /payment requests, and include the existing UPO payment method, which is linked to the customer’s Play+ account, as described in the steps below.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request.
2Use /getAccountDetails to retrieve details of the customer’s bank accounts enrolled (registered) in their Play+ account.
3Display these bank accounts to the customer, for them to select a bank account.
4Call the /payment request using sessionToken, userTokenId, and the existing userPaymentOptionId (UPO payment method), which is linked to the customer’s Play+ account, as shown below.

  • The userTokenId should be the same as was used when creating the Play+ account.

  • The userPaymentOptionId of the UPO linked to the customer’s Play+ account, was returned in the response to the first payment request sent for that customer’s Play+ account: response of payment request, (or the DMN returned by the payment request).

  • There may be a case where you would like to generate a UPO prior to a payment request. If so, then:

  • (If there is no userTokenId registered for this customer, then send a /createUser request, to register one.)

  • Send an /addUPOAPM to generate a userPaymentOptionId.
For further assistance, contact a member of Nuvei’s technical team.
5After processing the transaction, if urlDetails.notificationUrl was provided in the request, then Nuvei returns a DMN that includes the result of the transaction.
See an example DMN Response below.
Example /payment Request (with UPO)
{
    "sessionToken":"<sessionToken from getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "userTokenId":"<unique customer identifier in merchant system>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "currency":"USD",
    "amount":"200",
    "paymentOption":{
        "userPaymentOptionId":"8042541"
    },
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "cell":"6175553333",
        "phone":"6175551414",
        "zip":"02460",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "email":"john.smith@email.com"
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"john.smith@email.com",
        "phone":"6175551414",
        "cell":"6175553333",
        "dateOfBirth":"1970-06-30",
        "address":"22 Main Street",
        "city":"Boston",
        "zip":"02460",
        "county":"Suffolk",
        "state":"MA",
        "country":"US",
        "language":"en"
    },
    "deviceDetails":{
        "deviceType":"DESKTOP",
        "deviceName":"iPhone 5s",
        "deviceOS":"iOS 10.2",
        "browser":"safari",
        "ipAddress":"192.168.2.38"
    },
    "urlDetails":{
        "notificationUrl":"[The URL to which DMNs are sent]"
    },
    "customSiteName":"<CustomSiteName>",
    "productId":"VIDKI89DH30E",
    "customData":"<Custom Data>",
    "webMasterId":"8WQVRHRUHT7D",
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
Example /payment Response (with UPO)
{
    "reason":"",
    "orderId":"36241241",
    "transactionStatus":"APPROVED",
    "clientRequestId":"LUXOQ6ECZ",
    "internalRequestId":17696741,
    "version":"1.0",
    "transactionId":"2110000000004209142",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"XXZKDBYGEDWO",
    "errCode":0,
    "paymentOption":{
        "userPaymentOptionId":"8042541",
        "card":{
            
        }
    },
    "sessionToken":"763cfe0b-a239-41ae-8139-48c7f2e47367",
    "userTokenId":"E677539C0C54",
    "status":"SUCCESS"
}
Example /payment DMN Response (with UPO)
ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=36241241&userid=E677539C0C54&merchant_unique_id=XXZKDBYGEDWO&customData=Custom+Data%21&productId=&first_name=John&last_name=Smith&email=jhahn.jhnui%40srzaw.cb&currency=USD&clientUniqueId=XXZKDBYGEDWO&customField1=customField1-value&customField2=customField2-value&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=340689+Billing+Str.+Updated.&address2=&country=United+States&state=&city=Billing+City+Updated&zip=BNE+4895U&phone1=359888797070&phone2=&phone3=&client_ip=192.168.2.38&nameOnCard=&cardNumber=&bin=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&AuthCode=2684&AvsCode=&Cvv2Reply=&shippingCountry=US&shippingState=&shippingCity=Shipping+City+Updated&shippingAddress=33+Shipping+Str.+Updated.&shippingZip=SDC+33334U&shippingFirstName=john&shippingLastName=Uvnoirngbg&shippingPhone=359888576900&shippingCell=359887576903&shippingMail=gmwch.bphmv%40ducdb.qz&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=126006&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_PlayPlus&ID=&merchant_id=2502136204546424962&responseTimeStamp=2021-07-30.06%3A03%3A27&buyButtonProductId=&webMasterId=8WQVRHRUHT7D&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=E677539C0C54&userPaymentOptionId=8042541&TransactionID=2110000000004209142&externalTransactionId=723adaf0-185b-4118-afac-26fd3ec937ba&APMReferenceID=E2E47275310CC939863815B0A6ECAD20&orderTransactionId=18076831&totalAmount=10.00&dynamicDescriptor=MerchantNameDescriptor123456789101112131415&item_name_1=Item+1U&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20210709&shippingCounty=SCountyU&type=DEPOSIT&clientRequestId=LUXOQ6ECZ&relatedTransactionId=&responsechecksum=ff4e34fec4c9c83bfa184e4e606ca989&advanceResponseChecksum=54182705431a578e4898a1385d527e48

Payout – REST

You can send REST API /payout requests (withdrawal transactions) for Play+, as described in the steps below.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request.
Use /getAccountDetails to retrieve details of the customer’s bank accounts enrolled (registered) in their Play+ account.
Display these bank accounts to the customer, for them to select a bank account.
2Call the /payout request and include the userPaymentOptionId returned in the response of payment request, (or the DMN returned by the payment request).

See an example /payout request below.

There may be a case where you would like to generate a UPO prior to a payment request. If so, then:

  • (If there is no userTokenId registered for this customer, then send a /createUser request, to register one.)

  • Send an /addUPOAPM to generate a userPaymentOptionId.
For further assistance, contact a member of Nuvei’s Technical Team.
3After processing the transaction, if urlDetails.notificationUrl was provided in the request, then Nuvei returns a DMN that includes the result of the transaction.
Example /payout Request
{
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "userTokenId": "<unique customer identifier in merchant system>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "currency":"USD",
    "amount":"200",
    "userPaymentOption":{
        "userPaymentOptionId":"8042761"
    },
    "deviceDetails":{
        "deviceType":"DESKTOP",
        "deviceName":"iPhone 5s",
        "deviceOS":"iOS 10.2",
        "browser":"safari",
        "ipAddress":"192.168.2.38"
    },
    "merchantDetails":{
        "customField1":"customField1-value",
        "customField2":"customField2-value"
    },
    "comment":"<comment>",
    "urlDetails":{
        "notificationUrl":"[The URL to which DMNs are sent]"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
Example /payout Response
{
    "reason":"",
    "transactionStatus":"APPROVED",
    "clientRequestId":"P5S49XKXW",
    "internalRequestId":17661371,
    "merchantDetails":{
        "customField1":"customField1-value",
        "customField2":"customField2-value"
    },
    "version":"1.0",
    "transactionId":"2110000000004199304",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":0,
    "userPaymentOptionId":"8042761",
    "paymentMethodErrorCode":"0",
    "userTokenId":"G480LNG2WYJ7",
    "externalTransactionId":"2110000000065431",
    "status":"SUCCESS"
}

x