Alternate Payment with Token
Paysafe Checkout currently supports the following Alternate Payment Methods (APM): Interac and PayPal. For more details, see the Alternate Payments API.
Once you have received the APM single-use token from Paysafe Checkout, you can use it to make a payment using the Alternate Payments API.
If your transactions are in multiple currencies you need to consider how you will handle the multiple merchant accounts involved and select the correct one to use when taking payment.
At present, Paysafe supports the following currencies:
- for PayPal: Most major currencies, including USD, CAD, GBP, EUR
- for Interac: CAD only
The payment endpoint uses the server-to-server API key. Do not use the Alternate Payments API from the client's web browser as this will expose this key.
Call the following Alternate Payments API endpoint from your server to make the payment:
POST /alternatepayments/v1/accounts/account_id/payments
curl -X POST https://api.test.paysafe.com/alternatepayments/v1/accounts/1001199750/payments \
-u test_username:B-qa2-0-59564dfa-0-302c021426a55dde98dc2a052cccc1ddc8daa776a7a4fe2e0214080388fded986767abc445e58af123c01003cb8b \
-H 'Content-Type: application/json' \
-d ' {
"merchantRefNum": "1537363109",
"amount": 5000,
"settleWithAuth": false,
"returnLinks": [{
"rel": "default",
"href": "https://mysite.com/return"
}],
"paymentType": "INTERAC",
"paymentToken": "AP97U2uORetNQZaO"
} '
Prior to trying the example, you should:
- Replace the account number (1001199750) in the URL with the Test account number you received from Paysafe for the APM provider.
- Replace the API key user name and password (after the -u) with the Test API key you received from Paysafe.
- Replace the payment type (INTERAC), if necessary, with the type of payment you are making. Currently, Interac and PayPal are supported.
- Replace the payment token (AP97U2uORetNQZaO) with the Test token you obtained in the resultCallback method (in the case where you have set the environment parameter to TEST).
The APM Payment request contains the following parameters.
| Element | Type | Description |
|---|---|---|
| amount | integer max=999999999 | This is the amount of the request, in minor units. |
| merchantRefNum | string length<=255 | This is the merchant reference number created by the merchant and submitted as part of the request. |
| settleWithAuth | boolean | This indicates whether the request is an Authorization only (no Settlement). This must be set to false. |
| paymentType | enum | This specifies the type of payment. This must be set to the payment type from the supported providers list, i.e., INTERAC or PAYPAL. |
| paymentToken | string | This is the payment token returned by Paysafe Checkout for the APM request. |
All the parameters in the table above are mandatory for the APM Payment request.
{
"id": "0643c070-15c0-4218-8af1-1dc82b4f93fc",
"merchantRefNum": "1537363109",
"amount": 5000,
"currencyCode": "CAD",
"paymentType": "INTERAC",
"settleWithAuth": false,
"availableToSettle": 5000,
"availableToRefund": 0,
"txnTime": "2018-09-19T13:17:35Z",
"status": "COMPLETED",
"gatewayResponse": {
"id": "d3188d9c-f81a-4958-8505-03764bf577f2"
"processor": "INTERAC"
},
"links": [{
"rel": "self",
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1001199750/payments/0643c070-15c0-4218-8af1-1dc82b4f93fc"
}]
}
The APM Payment response contains the following additional parameters.
| Element | Type | Description |
|---|---|---|
| id | string | This is the unique ID for this APM payment. |
| currencyCode | string | This is the currency of the payment. Defaults to the account currency. |
| availableToSettle | number | This is the amount remaining to settle, in minor units. |
| availableToRefund | number | This is the amount remaining to refund, in minor units. |
| txnTime | UTC formatted date | This is the date and time the transaction was processed. E.g., 2017-12-11T16:33:49Z |
| status | enum | This is the status of the request. |
| gatewayResponse | object | These are the details returned from the external gateway. |
| links | array of link objects | This is an array of links related to the resource. |
PayPal's Seller Protection and Responsible Gambling Policy
The PayPal Seller Protection policy can protect a merchant's transactions from chargebacks and reversals and their associated fees. This means that if a customer disputes a PayPal purchase they have made on your site, you may be eligible to retain the full purchase amount and avoid any related chargeback fees paid (for debit and credit card-funded transactions). PayPal Responsible Gambling policy allows merchants to uniquely identify the PayPal accounts used in relation to the consumer gambling accounts, so that the merchant can allow one PayPal account to be used with only one consumer gambling account.
In order to be covered by PayPal's Seller Protection and Responsible Gambling Policies, the merchant can follow these three easy steps.
For PayPal's Responsible Gambling policy, only steps 2 and 3 are enough, and step 1 is unnecessary.
- The merchant provides a customer's shipping address and shipping preference in the Paysafe Checkout request for PayPal.
- Paysafe returns a PayPal single-use token in the Checkout response (the token in the resultCallback) – use this token to do a lookup call using the Alternate Payments API. Through this lookup call, you can validate the customer's shipping address and PayerID (the payerId parameter), which are included in the response. (PayPal uses the PayerID to uniquely identify the customer and the merchant can then decide not to continue with the transaction if the same payerId is used with another consumer account registered at the merchant.)
- After you have validated the customer, you can use the payment token to make a payment with the Alternate Payments API. The token returned by the Checkout is used for the paymentToken in this Alternate Payments API call.
1. Using Paysafe Checkout to Set Up for PayPal Seller Protection
Here is how the Paysafe Checkout should be set up with a shipping address and a shipping preference in order to enable the PayPal Seller Protection:
var options = {
amount: 105,
paymentMethodHeaders: JSON.stringify(paymentMethodHeaders),
environment: env,
preferredPaymentMethod: "PAYPAL",
currency: "EUR",
companyName: "Example Inc.",
holderName: "Nikolay Diyanov",
shippingAddress: {
recipientName: "Brian Robinson",
street: "100 Queen Street",
street2: "201",
city: "San Jose",
country: "US",
zip: "95131",
state: "CA",
},
paymentMethodDetails: {
paypal: {
shippingPreference: "SET_PROVIDED_ADDRESS",
},
},
}
paysafe.checkout.setup(apiKey, options, function (instance, error, result) {
});
2. Verifying the Customer with the Alternate Payments API
After you receive the token in the Paysafe Checkout response, call the following Alternate Payments API endpoint from your server to verify PayerID and shipping address:
/alternatepayments/v1/accounts/account_id/initialpayments/paymenttoken
curl -X POST \
https://api.test.paysafe.com/alternatepayments/v1/accounts/1001264440/initialpayments/paymenttoken \
-u test_username:B-qa2-0-59564dfa-0-302c021426a55dde98dc2a052cccc1ddc8daa776a7a4fe2e0214080388fded986767abc445e58af123c01003cb8b \
-H 'Content-type: application/json' \
-H 'Live-Mode: false' \
-H 'Simulator: EXTERNAL' \
-d '{
"paymentToken":"APxWbE56G45X50l7"
}'
{
"id": "d8469a40-6afd-4566-9f8a-974ddb4cd5b2",
"merchantRefNum": "PayPal_12341234236",
"dupCheck": true,
"amount": 200,
"currencyCode": "EUR",
"paymentType": "PAYPAL",
"profile": {
"firstName": "Nikolay",
"lastName": "Iliyanov"
},
"shippingDetails": {
"recipientName": "Brian Robinson",
"street": "100 Queen Street",
"street2": "201",
"city": "San Jose",
"state": "CA",
"country": "US",
"zip": "95131"
},
"returnLinks": [{
"rel": "default",
"href": "https://mysite.com/return"
}],
"liveMode": false,
"txnTime": "2019-06-03T09:51:10Z",
"updatedTime": "2019-06-03T09:53:48Z",
"statusTime": "2019-06-03T09:53:48Z",
"status": "WAITING_FINALIZATION",
"gatewayResponse": {
"payerId": "2AGQAPZCY4XSQ",
"id": "PAY-6X1925138R289474GLT2O3EA",
"processor": "PAYPAL"
},
"paymentToken": "APxWbE56G45X50l7",
"links": [{
"rel": "self",
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1001264440/initialpayments/d8469a40-6afd-4566-9f8a-974ddb4cd5b2"
}],
"paypal": {
"consumerId": "metis-buyer@paysafe.com"
}
}
3. Making the Payment with the Alternate Payments API
Once you have verified the PayPal Payer ID (payerId parameter) and the customer's shipping address (shippingDetails object), you can call the following Alternate Payments API endpoint to make the payment:
/alternatepayments/v1/accounts/account_id/payments
curl -X POST https://api.test.paysafe.com/alternatepayments/v1/accounts/1001264440/payments \
-u test_username:B-qa2-0-59564dfa-0-302c021426a55dde98dc2a052cccc1ddc8daa776a7a4fe2e0214080388fded986767abc445e58af123c01003cb8b \
-H 'Content-Type: application/json' \
-H 'Live-Mode: false' \
-H 'Simulator: EXTERNAL' \
-d ' {
"merchantRefNum": "PayPal_12341234237",
"amount": 200,
"settleWithAuth": false,
"returnLinks": [{
"rel": "default",
"href": "https://mysite.com/return"
}],
"paymentType": "PAYPAL",
"paymentToken": "APxWbE56G45X50l7"
} '
{
"id": "b8a726f6-fe4d-45cb-b8ef-54f431f1aac5",
"merchantRefNum": "PayPal_12341234237",
"dupCheck": true,
"amount": 200,
"currencyCode": "EUR",
"paymentType": "PAYPAL",
"profile": {
"firstName": "Nikolay",
"lastName": "Iliyanov"
},
"shippingDetails": {
"recipientName": "Brian Robinson",
"street": "100 Queen Street",
"street2": "201",
"city": "San Jose",
"state": "CA",
"country": "US",
"zip": "95131"
},
"returnLinks": [{
"rel": "default",
"href": "https://mysite.com/return"
}],
"liveMode": false,
"txnTime": "2019-06-03T10:17:16Z",
"updatedTime": "2019-06-03T10:20:03Z",
"statusTime": "2019-06-03T10:20:03Z",
"status": "COMPLETED",
"gatewayResponse": {
"payPalAuthorizationId": "24673005BM8739416",
"payerId": "2AGQAPZCY4XSQ",
"id": "PAYID-LT2PHIA4TU30285CN593990P",
"processor": "PAYPAL"
},
"paymentToken": "APxWbE56G45X50l7",
"links": [{
"rel": "self",
"href": "https://api.test.paysafe.com/alternatepayments/v1/accounts/1001264440/initialpayments/b8a726f6-fe4d-45cb-b8ef-54f431f1aac5"
}],
"paypal": {
"consumerId": "metis-buyer@paysafe.com"
}
}