Search Overlay

Transaction with Payment Handle

Once you have received the single-use payment handle, you can use it to make a payment using the 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. 

The single-use handle is actually called a token when created by the SDKs and paymentToken when created by the Payments API. Also called a paymentToken when used with the Payments API for a payment, original credit, standalone credit or verification.

NOTE:  The payments endpoint uses the server-to-server API key. Do not use the Payments API from the client's web browser as this will expose this key.

Payments

See Process Payment for more information.

Call the following endpoint from your server to take payment:

POST /paymenthub/v1/payments

Payment request example

curl -X POST https://api.test.paysafe.com/paymenthub/v1/payments \
-u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
-H 'Content-Type: application/json' \
-d ' {
"merchantRefNum": "10f64573-65d8-4d14-8337-66264094662f",
"amount": 1407,
"currencyCode": "USD",
"dupCheck": false,
"settleWithAuth": true,
"paymentHandleToken": "SC7nzOK9blfEKX1r",
"description": "Demo Paysafe Js"
} '

Prior to trying the example, you should:

  • Replace the API key user name and password (after the -u) with the Test API key you have received from Paysafe.
  • Substitute the paymentToken with the Test card token you obtained from Paysafe.js.

If your account has AVS (address verification system) enabled, you must include a billing address in the authorization call using the billingDetails object. The billing address is the address of the card represented by the payment token. Note that Developer Center test accounts have AVS enabled.

Payment response example

{
"id": "3f7992f8-f550-42a7-bc10-79728a43d3c6",
"paymentType": "CARD",
"paymentHandleToken": "SC7nzOK9blfEKX1r",
"merchantRefNum": "10f64573-65d8-4d14-8337-66264094662f",
"currencyCode": "USD",
"settleWithAuth": false,
"txnTime": "2022-01-14T13:17:03Z",
"billingDetails": {
"street": "5335 Gate Pkwy",
"city": "Jacksonville",
"zip": "32256",
"state": "FL",
"country": "US"
},
"status": "COMPLETED",
"amount": 1407,
"preAuth": false,
"description": "Demo Paysafe Js",
"availableToSettle": 1407,
"gatewayResponse": {
"authCode": "151328",
"avsResponse": "MATCH",
"cvvVerification": "MATCH",
"serializable": true
},
"profile": {
"locale": "en",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@paysafe.com"
},
"card": {
"cardExpiry": {
"month": "3",
"year": "2025"
},
"cardType": "VI",
"cardBin": "411111",
"lastDigits": "1111",
"cardCategory": "CREDIT"
}
}

If the card specified or identified by a handle in the request is enrolled in 3DS, there will be an authentication object in the response and this will contain details of the enrollment.

Verifications

See Verification for more information.

Call the following endpoint from your server:

POST /paymenthub/v1/verifications

Verification request example

curl -X POST https://api.test.paysafe.com/paymenthub/v1/verifications \
-u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
-H 'Content-Type: application/json' \
-d ' {
"merchantRefNum": "10f64573-65d8-4d14-8337-66264094662f",
"amount": 1407,
"currencyCode": "USD",
"paymentHandleToken": "SC7nzOK9blfEKX1r",
"description": "Demo Paysafe Js"
} '

Prior to trying the example, you should:

  • Replace the API key user name and password (after the -u) with the Test API key you have received from Paysafe.
  • Substitute the paymentToken with the Test card token you obtained from Paysafe.js.

If your account has AVS (address verification system) enabled, you must include a billing address in the authorization call using the billingDetails object. The billing address is the address of the card represented by the payment token. Note that Developer Center test accounts have AVS enabled.

Verification response example

{
"id": "25b74efe-16da-4975-a9d9-ef0df8bc1b5c",
"paymentType": "CARD",
"paymentHandleToken": "SC7nzOK9blfEKX1r",
"merchantRefNum": "10f64573-65d8-4d14-8337-66264094662f",
"currencyCode": "USD",
"txnTime": "2024-08-29T06:00:17Z",
"billingDetails": {
"street": "5335 Gate Pkwy",
"city": "Jacksonville",
"zip": "32256",
"state": "FL",
"country": "US"
},
"customerIp": "172.10.12.64",
"status": "COMPLETED",
"description": "Winning payment from Loto 649",
"gatewayResponse": {
"authCode": "828817",
"avsResponse": "NOT_PROCESSED",
"cvvVerification": "MATCH",
"nameVerification": "NOT_PROCESSED",
"serializable": true
},
"card": {
"cardExpiry": {
"month": "10",
"year": "2025"
},
"holderName": "Dilip",
"cardType": "VI",
"cardBin": "400000",
"lastDigits": "1091",
"cardCategory": "DEBIT",
"issuingCountry": "US"
}
}

Standalone credits

See Process Standalone Credit for more information.

Call the following endpoint from your server:

POST /paymenthub/v1/standalonecredits

Standalone credit request example

curl -X POST https://api.test.paysafe.com/paymenthub/v1/standalonecredits \
-u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
-H 'Content-Type: application/json' \
-d ' {
"merchantRefNum": "10f64573-65d8-4d14-8337-66264094662f",
"amount": 1407,
"currencyCode": "USD",
"paymentHandleToken": "SC7nzOK9blfEKX1r",
"description": "Demo Paysafe Js"
} '

Prior to trying the example, you should:

  • Replace the API key user name and password (after the -u) with the Test API key you have received from Paysafe.
  • Substitute the paymentToken with the Test card token you obtained from Paysafe.js.

If your account has AVS (address verification system) enabled, you must include a billing address in the authorization call using the billingDetails object. The billing address is the address of the card represented by the payment token. Note that Developer Center test accounts have AVS enabled.

Standalone credit response example

{
"id": "e075f2ae-dfc4-4f6d-8d89-61158367b6a6",
"amount": 1407,
"merchantRefNum": "10f64573-65d8-4d14-8337-66264094662f",
"paymentHandleToken": "SC7nzOK9blfEKX1r",
"customerIp": "204.91.0.12",
"currencyCode": "USD",
"paymentType": "CARD",
"status": "PENDING",
"description": "Demo Paysafe Js""
}

Original credits

See Process Original Credit for more information.

Call the following endpoint from your server:

POST /paymenthub/v1/originalcredits

Original credit request example

curl -X POST https://api.test.paysafe.com/paymenthub/v1/originalcredits \
-u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
-H 'Content-Type: application/json' \
-d ' {
"merchantRefNum": "10f64573-65d8-4d14-8337-66264094662f",
"amount": 1407,
"currencyCode": "USD",
"paymentHandleToken": "SC7nzOK9blfEKX1r",
"description": "Demo Paysafe Js"
}

Prior to trying the example, you should:

  • Replace the API key user name and password (after the -u) with the Test API key you have received from Paysafe.
  • Substitute the paymentToken with the Test card token you obtained from Paysafe.js.

If your account has AVS (address verification system) enabled, you must include a billing address in the authorization call using the billingDetails object. The billing address is the address of the card represented by the payment token. Note that Developer Center test accounts have AVS enabled.

Original credit response example

{
"amount": 1407,
"merchantRefNum": "10f64573-65d8-4d14-8337-66264094662f",
"paymentHandleToken": "SC7nzOK9blfEKX1r",
"customerIp": "204.91.0.12",
"description": "Demo Paysafe Js"
}

Converting a single-use token to a permanent token

You can convert the single-use token to a reusable permanent payment token by using it to create a profile in the Payments API. We recommend you verify that the single-use token corresponds to a valid card before creating a reusable permanent payment token (also known as a multi-use payment handle or multi-use token).