PaysafeCash
PaysafeCash is a barcode-based eCash payment solution that empowers various industries, including financial services, housing, government, utilities, healthcare, and gaming, to accept payments in cash. With PaysafeCash, products or services can be ordered online and then paid for directly with cash at the nearest PaysafeCash payment point by scanning a barcode. It operates in over 30 countries and has over 200,000 participating partner stores.
PaysafeCash at a glance
| Payment type | eCash |
|---|---|
| Consumer markets | Global |
| The consumer is debited in | USD |
| Processing currency | EUR, USD, ARS, AUD, BGN, CAD, CHF, CZK, DKK, GBP, HRK, HUF, LTL, LVL, NOK, MXN, NZD, PEN, PLN, RON, SEK, SKK, TRY, UYU (To see latest availability, see Availability of products.) |
| Single payments | YES |
| Merchant-initiated payments | No |
| Withdrawals | NO |
| Disputes | NO |
| Guarantee | NO |
| Refunds | NO |
| Reporting | You can review your transactions in the Paysafe Business Portal. |
| Funding | N/A |
| Languages supported | EN |
| Dynamic descriptor | YES |
| Additional Services | Store Locator (API-Based) Cancel Barcode (API-Based) |
Setup Requirements
1. Get Onboarded at Paysafe and receive your credentials as mentioned here.
2. Our integrations team will onboard you with PaysafeCash as a merchant.
3. Once both onboardings are done, our Integrations team will coordinate with you to get the following details:
| Parameter | Type | Type | Description |
|---|---|---|---|
| SubMerchantID | Alphanumeric | Conditional | This is a unique key that is used for reporting in case there are multiple products or multiple accounts in use. |
| MerchantID | Numeric | Mandatory | This is a 10-digit Parent Account ID unique for each merchant which will be used for all PaysafeCash products and integrations. |
| Apikey | Alphanumeric | Mandatory | A unique API key access credential is assigned to your merchant account, enabling secure and authenticated communication. |
All the details mentioned above can be found in your PaysafeCash Business Portal.
4. Finalize how you want to handle incomplete transactions, auto-settlement, or auto-refund as the last step. The exact use cases are mentioned below.
Typical Scenarios
Payments
In payments, for PaysafeCash, below-mentioned steps can be taken to process a payment:
Setup:
- Provide the Public API key:
- Provide the options:
- currency, amount, merchantRefNum, customer.
- paymentMethodDetails object is mandatory; it should contain PaysafeCash object with consumerId which is a unique ID for the user provided by the merchant.
- Create a resultCallback function to capture the details of the transaction.
- Optional closeCallback to know the status of payment handle before taking the next action.
Server-to-Server Calls
Payments API Call:
- From the resultCallback function in result capture the amount, paymentHandleToken and transactionType.
- If transactionType matches PAYMENT, trigger Payments API.
In PaysafeCash, since the payment is not completed until the user goes to an outlet and pays the complete amount, the status of payment would be PROCESSING.
3. In the Payments API call, the parameter settleWithAuth can be set depending upon the expected outcome,
- If the value is set to TRUE, then as soon as the user completes the transaction the settlement will also be done and Payments and Settlement both will be completed automatically.
- If the value is set to FALSE, then as soon as the user completes the transaction Payment will move to completed and a webhook will be triggered to the merchant confirming the same, then the merchant needs to call the settlement API to complete the transaction.
Settlement API Call:
- From the Payments API webhook or GET call for the Payment ID the merchant can identify the transaction status, if it is COMPLETED and settleWithAuth is FALSE, the merchant should trigger Settlement API, else if it is COMPLETED and settleWithAuth is TRUE, Settlement API call is not needed by the merchant, Paysafe will automatically trigger it.
If the merchant fails to trigger Payments API or the Settlement API call for any reason, Paysafe offers the auto-settlement and auto-refund options, which the merchant can pre-configure.
Case 1: Payments API call is not triggered by the merchant
In auto-settlement, Paysafe will actively check the transaction status at the PaysafeCash end. If the transaction is completed, Paysafe will move the paymentHandleToken to the COMPLETED state and automatically trigger Payments and Settlement. However, if the transaction is not completed by the user, Paysafe will move the paymentHandleToken to the EXPIRED state, resulting in no payments or settlement call.
In auto-refund, Paysafe will actively monitor the status of the transaction, complete it, and then initiate a refund to the user.
Case 2: Payments API call is triggered where settleWithAuth=FALSE, but Settlement API is not triggered by the merchant
In auto-settlement, Paysafe will actively check the status of the payment, move it to COMPLETED status, and automatically trigger the Settlement API call.
In auto-refund, Paysafe will actively check the status, complete the transaction, and then initiate a refund to the user.
Sample Code
Payments: User Email Locked
<html>
<head>
<script src="https://api.test.paysafe.com/checkout/v2/paysafe.checkout.min.js"></script>
</head>
<body>
<button onclick="checkout()">Deposit</button>
</body>
<script>
function checkout() {
var API_key = "c3V0LTM0ODg2MDpCLXFhMi0wLTVkM2VjYjMwLTEtMzAyYzAyMTQyYTM3NjgxMmE2YzJhYzRlNmQxMjI4NTYwNGMwNDAwNGU2NWI1YzI4MDIxNDU1N2EyNGFiNTcxZTJhOWU2MDVlNWQzMjk3MjZjMmIzZWNjNjJkNWY=";
options = {
currency: "USD",
amount: 540,
merchantRefNum: "162938285366512",
customer: {
firstName: "John",
lastName: "Doe",
email: "DoeJohn.0309@gmail.com",
},
paymentMethodDetails: {
PaysafeCash: {
consumerId:"MerchantClientID"
}
}
};
paysafe.checkout.setup(
API_key,
options,
function resultCallback(instance, error, result) {
if (result && result.paymentHandleToken) {
instance.showSuccessScreen( "Your goods are now purchased. Expect them to be delivered in next 5 business days.");
if (instance.isOpen()) {
instance.close();
}
//Check paymentHandleToken Stage to initiate next step
} else {
console.error(error); // Handle the error
instance.showFailureScreen( "The payment was declined. Please, try again with the same or another payment method.");
}
},
function(stage, expired) {
if (stage) {
switch (stage) {
case "PAYMENT_HANDLE_NOT_CREATED" :
case "PAYMENT_HANDLE_CREATED" :
case "PAYMENT_HANDLE_REDIRECT" :
case "PAYMENT_HANDLE_PAYABLE" :
default:
}
}
else {
console.log(expired) //Add action in case Checkout is expired
}
}
);
}
</script>
</html>
Store Locator
The Store Locator API provides a list and details of payment points around a geographic location, for more details, find here
Cancel Barcode
This API allows merchants to cancel a generated barcode before the user has completed the offline payment at the store, for more details. see API docs.
Code Examples
Payments API
Payments API Request:
{
"amount": 540,
"merchantRefNum": "131d5ceb-d1fa-4685-bb9f-6eeec34b57ac",
"currencyCode": "GBP",
"paymentHandleToken":"PH0QpP6fA2ghBUX0"
}
Payments API Response:
{
"id": "131d5ceb-d1fa-4685-bb9f-6eeec34b57ac",
"paymentType": "PAYSAFECASH",
"paymentHandleToken": "PH0QpP6fA2ghBUX0",
"merchantRefNum": "74c7f2ae4796c7fa475d",
"currencyCode": "GBP",
"settleWithAuth": true,
"dupCheck": true,
"txnTime": "2023-12-08T00:51:46Z",
"billingDetails": {
"street1": "2nd",
"street2": "Peachtree Place",
"city": "Atlanta",
"zip": "90001",
"state": "GA",
"country": "US"
},
"customerIp": "10.195.88.177",
"status": "COMPLETED",
"gatewayReconciliationId": "pay_1000005455_Ei6RErkYeZxkvImN7fkuKaDbP0cOmfUC_GBP",
"amount": 540,
"availableToRefund": 540,
"consumerIp": "10.195.88.177",
"liveMode": false,
"simulator": "EXTERNAL",
"updatedTime": "2023-12-08T00:53:12Z",
"statusTime": "2023-12-08T00:53:12Z",
"gatewayResponse": {
"id": "pay_1000005455_Ei6RErkYeZxkvImN7fkuKaDbP0cOmfUC_GBP",
"processor": "PAYSAFECARD"
},
"availableToSettle": 0,
"profile": {
"firstName": "John",
"lastName": "Doe",
"email": "Doe.John@gmail.com"
},
"paysafecash": {
"consumerId": "merchantClientID"
},
"settlements": [
{
"amount": 540,
"txnTime": "2023-12-08T00:51:46.000+0000",
"availableToRefund": 540,
"merchantRefNum": "74c7f2ae4796c7fa475d",
"id": "131d5ceb-d1fa-4685-bb9f-6eeec34b57ac",
"status": "COMPLETED"
}
]
}
Settlement API
Payments API Request:
POST: /paymenthub/v1/payments/{PaymentResponse.Id}/settlements
{
"merchantRefNum": "b1c58505-a7b5-4a7e-a852-9597807c3af6",
"dupCheck": true,
"amount": "500"
}
Payments API Response:
{
"id": "b1c58505-a7b5-4a7e-a852-9597807c3af6",
"paymentType": "PAYSAFECASH",
"merchantRefNum": "113e922d51f-a580-42d7-b587-cc594b14873a",
"currencyCode": "USD",
"txnTime": "2023-12-10T14:18:09Z",
"status": "COMPLETED",
"gatewayReconciliationId": "c5a41ec0-f4d0-4b2e-9f86-6cfc3989c604",
"amount": 5200,
"simulator": "INTERNAL",
"liveMode": false,
"updatedTime": "2023-12-10T14:18:09Z",
"statusTime": "2023-12-10T14:18:09Z",
"availableToRefund": 5200,
"gatewayResponse": {
"id": "c5a41ec0-f4d0-4b2e-9f86-6cfc3989c604",
"processor": "PAYSAFECARD"
}
}