PaysafeCard

PaysafeCard is a popular alternative payment method that enables customers to make online purchases without the need for a bank account or credit card. Customers can purchase prepaid vouchers from authorized retailers and then redeem them at various online platforms, including gaming, e-commerce, and entertainment sites. With its widespread availability and ease of use, PaysafeCard offers a secure and convenient solution for customers seeking a flexible payment option for their online transactions.

Features

1. Broad acceptance across industries: PaysafeCard is widely accepted by various online platforms, from gaming to e-commerce and entertainment. 

2. Secure and private transactions: With PaysafeCard, customers can make purchases online without sharing personal or financial information.

3. No bank account or credit card is required: PaysafeCard eliminates the requirement for traditional banking services, making it accessible to all.

4. Flexible payment amounts: Customers can choose the desired denomination for prepaid vouchers, allowing for customized payment options.

5. Convenient accessibility: PaysafeCard vouchers can be easily obtained from authorized retailers or online channels, ensuring widespread availability.

The Payments API caters to the following needs of PaysafeCard:

• Payment Instrument: PaysafeCard, PaysafeCard account, Scan to Pay. 
• Prepaid Payment Method: Pay online without entering any personal information, bank, or credit card details. 
• Transaction types: Payments, Withdrawals, and Refunds. 
• Payment authentication: PIN protected (Payment Services Directive 2 (PSD2) Compliance)

To see the availability of products, click here.

To process a payment request using PaysafeCard: 

1. Create a payment handle with the following parameter settings:
   transactionType: PAYMENT
   paymentType: PAYSAFECARD
   POST: paymenthub/v1/paymenthandles
2. Paysafe returns a response with the following details:
   • The action parameter is set to REDIRECT
   • A payment_redirect link points to PaysafeCard page redirect URL
   • The status of the payment handle becomes INITIATED.
3. After the customer is redirected using payment_redirect on the PaysafeCard page, the customer gets different options to pay depending upon merchant configuration and the currency of the transaction:
   • 16-Digit BIN
   • PaysafeCard Account 
   • Scan to Pay
     Note: Only payment with the PaysafeCard account option makes the customer eligible for the payout service.
     
4. Depending on the status of the transaction, the customer is redirected to the success or failure page.
   • The status of the payment handle becomes PAYABLE after a successful transaction and becomes FAILED, if the transaction fails.
   • You get notified of the status change through a configured webhook.
5. Use the paymentHandleToken returned in the response to process the payment request.
   POSTpaymenthub/v1/payments

6. In the response to the Payments API call, depending on your configured account at PaysafeCard and the processing currency, and the customer action, the response contains these parameters. 

   • The Id returned in the response is the payment ID, and it's the same as the settlement ID if settleWithAuth is set to TRUE, and must be stored at your end for future use, as paymentId is used in refunds directly.

   • If the Payment API request is done and settleWithAuth is set to FALSE, the Settlement API can be called separately. 
     • POST: paymenthub/v1/settlements
     • In this case, a new and separate Id from the Payments ID is returned in the response, and this should be stored at the merchant's end for future use, as settlementId is used in refunds directly and not paymentId. 

You can request the consumer's consent to initiate future transactions in their name. You can either facilitate recurring payments, or one-click payments without the need for the consumer to be redirected or to log into a PaysafeCard account.

Note: The merchant-initiated transactions feature must be enabled at a MID level while onboarding by emailing Merchant Services <merchant-services@paysafe.com>.

Consent during the first payment

While initiating a payment, you can pass the automaticPaymentConsent parameter to the payment handle request.  

• If the parameter is set to optional, a consent checkbox will be enabled when the consumer pays for their transaction. If you send this parameter, the consumer's associationId will be returned in the payment handle response. The association ID will only be active if the consumer accepts the consent checkbox.
• If the parameter is set to mandatory, a text appears to inform the customer about the consent given and to agree and continue. 

To process a payment request with consumer consent: 

1. Create a payment handle with the following parameter settings:
   transactionType: PAYMENT
   paymentType: PAYSAFECARD
   POST: paymenthub/v1/paymenthandles
2. An additional parameter automaticPaymentConsent needs to be passed under the PaysafeCard object. This parameter can be set to either OPTIONAL or MANDATORY. 
3. After the consumer is redirected using payment_redirect on the PaysafeCard page, a consent screen appears and the consumer needs to login and complete the transaction using their PaysafeCard account.
4. Depending on the status of the transaction, the consumer is redirected to either the success or failure page. 
   • The status of the payment handle becomes PAYABLE after a successful transaction and becomes FAILED, if the transaction fails.
   • You get notified of the status change through a configured webhook with automaticPaymentConsent and associationId in payment handle webhooks.
   • In the response, you will receive associationId for the payment consent given by the customer. 
5. Use the paymentHandleToken returned in the response to process the payment request.
   POST: paymenthub/v1/payments
6. In the response to the Payments API call, depending on your configured account and processing currency at PaysafeCard, the response contains parameters as displayed in the following code examples. 
   • The settleWithAuth will be passed as TRUE and the Id returned in the response is the paymentId and it is the same as the settlement ID and must be stored at your end for future use, as paymentId is used in initiating refunds directly. 
7. After the consumer gives the consent, the consent details are required to be saved at Paysafe.
   • Call the endpoint with basic customer details like firstName, lastName, and email, along with merchantCustomerId (Customer id generated using the Customer API) 
   • POST: paymenthub/v1/customers
   • The consumer will be created, and id will be returned as an identifier of the consumer. 
8. Create a consumer: save the consent details to the consumer profile at Payment Handle Customer API using the id returned in the first call and paymentHandleToken as parameter paymentHandleTokenFrom
   • POST: paymenthub/v1/customers/{id}/paymenthandles
   • The consent details are saved, and a permanent token (multi-use payment handle token) is sent as paymentHandleToken.   

Recurring Payments 

1. The permanent tokens((multi-use payment handle) can be fetched by doing a GET call on the customer ID using the Customer Payment Handles API
   • GET: paymenthub/v1/customers/{id}?fields=paymenthandles
2. In the response, the consent details are sent as a permanent token (multi-use payment handle token) in the parameter paymentHandleToken.  
3. The paymentHandleToken is used to call the Payments API to process the recurring payment requests. 

Points to consider: 

1. You should store the multi-use payment handle token in your database to initiate future customer transactions. Suppose you trigger a payment handle API call with the same consumerId. In that case, the existing multi-use payment handle token will be cancelled, and you will need to create a payment handle request again and obtain consent from the customer, followed by payment completion and the generation of a new multi-use payment handle token ID.
2. If the customer cancels the consent, you will receive the webhook for the multi-use payment handle cancelled from Paysafe. You need to create a payment handle request again and get permission from the customer, followed by payment completion and the generation of a new multi-use payment handle token ID.
3. The consent is valid for 365 days. After the consent has expired, Paysafe will send a webhook notification to the merchant that the multi-use payment handle has expired. You need to create a payment handle request again and get consent from the customer, followed by payment completion and the generation of a new multi-use payment handle token ID. 
4. After the payment handle call, the generated redirect URL is valid for 15 minutes. You must create a new payment handle request if consent takes more than 15 minutes.
5. If you send countryRestriction in the payment handle request and the customer's country is different, then the customer will be able to give consent but not be able to complete the payment. 

You can request consent from the consumer separately without initiating a transaction. For this, you need to initiate a payment handle and request consent from the consumer. Once the consumer gives consent, the associationId will be returned in the payment handle response. After this, you can initiate payments at any time using a multi-use payment handle (MUPH) token to complete the transaction. 

To get consent from the consumer before initiating payments:

1. If you do not have an existing customer ID, create one using below steps:

   • Call the endpoint with basic customer details like firstName, lastName, and email, along with merchantCustomerId (customer id generated using the Customer API) POST: paymenthub/v1/customers
   • The consumer will be created, and id will be returned as an identifier of the consumer. 
   • For an existing customer, if you want to get the customer ID using merchant customer id, call the below API request:
     • GET: paymenthub/v1/customers?merchantCustomerId={merchantCustomerId}

     • GET:

     • paymenthub/v1/customers/{customerId}?fields=paymenthandles
2. Create a multi-use payment handle: 
   POST: paymenthub/v1/customers/{customerId}/paymenthandleswith the following parameter settings:
   paymentType: PAYSAFECARD
   This multi-use payment handle is created without specifying the amount parameter. The payment handle is valid for 365 days until the consumer cancels the consent. 
3. The above step returns a redirect URL and the consumer is redirected using payment_redirect on the PaysafeCard page, and the consumer is displayed the consent screen.
   • At this point, the multi-use payment handle token will be in an initiated state.
   • The consumer needs to provide consent, after which the multi-use payment handle token will move to payable. 
   • The redirect URL is valid for 60 minutes.  
4. Depending upon the status of the multi-use payment handle token: 
   • After the consumer has provided consent successfully, the status of the multi-use payment handle becomes PAYABLE. 
   • If the consumer cancels the consent or consent expires (365 days from the date of the consent), you get notified of the status change through a configured webhook in the payment handle. 
   • In the response, you will receive an associationId for the payment consent given by the consumer. 
   • The field ispaymentconsent gives the status of consent given by the consumer.

To process a payment request using PaysafeCard with consumer consent already provided: 

1. Use the multi-use paymentHandleToken returned in the response. 
   POST:paymenthub/v1/payments

2. In response to the Payments API call, depending upon your configured account at PaysafeCard, the processing currency, and the consumer action:

   • The settleWithAuth is passed as TRUE and the Id returned in the response is the paymentId and it is the same as the settlement ID and must be stored at your end for future use, as paymentId is used in initiating refunds directly. 
3. If you need to check the consent provided by a particular consumer, you need to call this API
   GET: paymenthub/v1/customers/{customerId}/paymenthandles/{paymenthandleId}

Points to consider: 

1. You should store the multi-use payment handle token in your database to initiate future transactions for the consumer. If you trigger a payment handle API call with the same consumerId, then the existing multi-use payment handle token gets cancelled, and you need to create a payment handle request again and get consent from the consumer.
2. If the consumer cancels the consent, then you get notified via a webhook. You need to create a payment handle request again and get consent from the consumer. 
3. The consumer consent is valid for 365 days from the date of the consent. After the consent has expired, Paysafe will send a webhook notification to you that the multi-use payment handle has expired. You need to create a payment handle request again and get a new consent from the consumer. 

PaysafeCard payouts allow the transfer of funds to the PaysafeCard account holders. Payout is executed by the business partner at the demand of the customer. 

Payouts are currently only available for PaysafeCard account holders in the following countries: 

To process a PaysafeCard withdrawal request:

1. Create a payment handle with the following parameter settings:
   transactionType: STANDALONE_CREDIT
   paymentType: PAYSAFECARD
   POST:paymenthub/v1/paymenthandles

2. The request needs two objects 

   • PaysafeCard which will take 2 parameters

   • profile object of the request will take 4 parameters. 

3. In the response, a one-time token will be received with the tag paymentHandleToken and the status turns to PAYABLE, this token is then passed to the Standalone Credits API. 
   POST: paymenthub/v1/standalonecredits
4. The final response will contain the details of the transaction with parameters like
   • id - unique identifier at Paysafe
   • gatewayReconciliationId - unique identifier at Skrill
   • Status of the transaction that can be used for future reference.
5. The status of the withdrawal will be PENDING initially and move to COMPLETED once the refund is processed to the consumer's bank account, at each step a webhook will be triggered to you. 

To process a refund transaction using PaysafeCard:

You can initiate a refund transaction only for a transaction whose settlement/payment is completed.

1. After the payment and then settlement are done
   • The status is COMPLETED in the response of payments information
   • The refund can be initiated using the Settlement ID which is the same as Payment ID if settleWithAuth is TRUE.
2. Create a refund request with the Refunds API. 
   POST: /paymenthub/v1/settlements/{settlementId }/refunds
3. The response contains details of the payment and a unique identifier that could be used to refer to each individual refund, either partial or full.
4. The status of the refund will be PENDING initially and moves to COMPLETED once the refund is processed to the customer's bank account, at each step a webhook will be triggered to you. 

Note: A refund transaction can only be initiated by you and for a transaction whose settlement/payment is completed. Partial refunds are not available. 

You can retrieve the balance in your accounts using the Get Balance API. The API call is a GET request and returns an array of account balances.

Note: While onboarding a customer to PaysafeCard, contact Paysafe Integration Team and get this feature enabled for your account. 

Sample Request:

GET: https://api.test.paysafe.com/paymenthub/v1/balances?paymentType={paymentType}&currencyCode={currencyCode}

Payments API response parameters

PaysafeCard object

profile object

Test Customer Id Values

Customer ID is also known as Merchant Client ID, is an important parameter for the integration of PaysafeCard. The Customer ID identifies the Customer on our business partners side. The most optimal customer ID is a completely random value. A value that uniquely identifies the customer and is disconnected from any personal information. This customer ID value should be the same for all transactions of the customer. Here are Guidelines for possible Customer IDs:

Valid Values:

Invalid Values

Sending any form of the invalid values will not be accepted. If you intend to process PaysafeCard transactions on multiple brands, please inquire about the possibilities of separating multiple entities for your account.

Payment Handle

1. PAYMENT_HANDLE_PAYABLE – This webhook signifies that the payment handle token created for the required purpose can now be executed, and the preliminary requirements are completed, the next API call with the payment handle can be done.
2. PAYMENT_HANDLE_PROCESSING – This webhook is triggered when the user is successfully redirected to the payment platform page and operation has started for the payment by the user.
3. PAYMENT_HANDLE_COMPLETED – This webhook is triggered when the process of the payment handle is token is completed after triggering the next API, Payments or Standalone Credit API.
4. PAYMENT_HANDLE_EXPIRED – This webhook is triggered when the next step is not initiated after the payment handle is created within the given time frame, the duration can be seen in the response to /paymenthub/v1/paymenthandles API under the tag timeToLiveSeconds.

Payments

1. PAYMENT_PROCESSING: The payment is in progress. In some cases, there might be delays due to an action pending by you or the customer. 
2. PAYMENT_PENDING - The payment is pending because the transaction hasn't been completed from the bank account to Skrill wallet to you.
3. PAYMENT_COMPLETED/SETTLEMENT_COMPLETED – The payment was completed successfully.
4. PAYMENT_FAILED – This webhook is triggered when the payment fails during the process.

Settlement

1. SETTLEMENT_FAILED - This webhook is triggered in case the transaction was initially completed and later failed due to some settlement error.
2. SETTLEMENT_CANCELLED - This webhook is triggered when the transaction was cancelled after it was completed
3. SETTLEMENT_ERRORED - This webhook is used when there is a technical error during the initiation of a transaction.
4. SETTLEMENT_PENDING - This webhook is triggered when the withdrawal has been initiated but due to various bank delay reasons or time zone issues the actual money transfer has not happened.

Standalone Credits/Withdrawal

1. SA_CREDIT_FAILED - This webhook is triggered in case the transaction was initially completed and later failed due to some settlement error.
2. SA_CREDIT_CANCELLED - This webhook is triggered when the transaction was cancelled after it was completed
3. SA_CREDIT_ERRORED - This webhook is used when there is a technical error during the initiation of a transaction.
4. SA_CREDIT_PENDING - This webhook is triggered when the withdrawal has been initiated but due to various bank delay reasons or time zone issues the actual money transfer has not happened.

Refunds

1. REFUND_FAILED - This webhook is triggered when the refund is initiated but failed due to a functional error for refund amount is more than the payment amount.
2. REFUND_COMPLETED - This webhook is triggered when the refund has been successfully transferred from merchant account to the user's chosen bank account
3. REFUND_PENDING - This webhook is triggered when refund has been initiated but due to various bank delay reasons or time zone issues the actual money transfer has not happened.