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

Request Example
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.
Response Example
{
	"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.
  1. The merchant provides a customer's shipping address and shipping preference in the Paysafe Checkout request for PayPal.
  2. 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.)
  3. 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

Request Example
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"
}'
Response Example
{
	"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

Request Example
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"
} '
Response Example
{
	"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"
	}
}
Did you find this page useful?