Cards

The Paysafe Payments API supports Cards as a Payment Instrument. You can process card payments using the Payments API and store instrument details for future payments. You can also store multiple cards on a customer to charge the customer later.

The Payments cater to the following needs for CARDS:

  • Payment Instrument: Credit cards, Debit cards
  • Cards Supported: Visa, Visa Debit, Visa Electron, Visa Prepaid, American Express, JCB, Mastercard, Mastercard Debit (Maestro), Mastercard Prepaid, Discover.
  • Transaction types: Payments, Refunds
  • Payment authentication: Dynamic 3D Secure 2 (ready for Strong Customer Authentication)

Typical Scenarios

This section illustrates some common scenarios to setup Payment and Credit requests.

Scenario 1: Card Payment with Settlement

Authorization and Settlement of a credit card payment are completed in a single request. This is usually used for providing immediate service. For example, a gaming merchant where a customer deposits money into their account. You would typically do the following:

  1. Create a Payment Handle having an immediate status of PAYABLE.
  2. Use the paymentHandleToken returned in response to process the Payment request – set the settleWithAuth parameter to true.
  3. Once the Payment request is successful, funds are immediately requested from the card issuer with the next Paysafe batch Settlement run.

APIs to use: Payment Handles + Payments

Scenario 2: Card Payment with Settlement with 3D Secure Authentication

Authorization and Settlement are completed in a single request. 3DSecure authentication is also done before Payment authorization.

You would typically do the following:

  1. Create a Payment Handle.
  2. Paysafe returns a response with the following:
    • The action parameter is set to REDIRECT (as 3Dsecure is enabled)
    • A payment_redirect link points to the 3D Secure authentication URL
  3. Redirect the customer to the 3D Secure authentication URL.
  4. Upon successful authentication, the merchant gets notified at the URL specified in the on_completed parameter included with their request.
  5. The status of the Payment Handle now becomes PAYABLE.
  6. Use the paymentHandleToken returned in response to process the Payment request – set the settleWithAuth parameter to true.
  7. Once the Payment request is successful, funds are immediately requested from the card issuer with the next Paysafe batch Settlement run.

APIs to use: Payment Handles + Payments

Scenario 3: Card Payment with Delayed Settlement

A merchant gets a purchase authorization for an amount and settles it after the service is fulfilled. An example would be a merchant who ships goods – after taking an online order on day one following the authorization, but then settle it on day 3 when they send the products you have purchased. You would typically do the following:

An example would be a merchant taking an online order on day one after authorization and then settling it on day three after shipping the goods.

  1. Create a Payment Handle having an immediate status of PAYABLE.
  2. Use the paymentHandleToken returned in response to process the Payment request – set the settleWithAuth parameter to false.
  3. Use the same paymentHandleToken to process a Settlement request after shipping the goods. The payment_id to include in the Settlement request URL is returned in response to the Payment Request.
  4. Funds are immediately requested from the card issuer with the next Paysafe batch Settlement run after the settlement request is completed.

You can make multiple Settlement requests to complete the initial Payment request, up to the full amount on the original authorization.

APIs to use: Payment Handles + Payments + Settlements

Scenario 4: Card Original Credit

Original Credit request allows a merchant to issue a credit to a customer when no previous Payment is tied to it. , as is the case with a regular Refund. For example, an online gaming merchant may want to perform a payout using an Original Credit. In this scenario, you would do the following:

  1. Create a Payment Handle, with the transactionType parameter set to ORIGINAL_CREDIT. This Payment Handle should immediately have the status of PAYABLE.
  2. Use the paymentHandleToken returned in response to process the Original Credit.

Once the Original Credit request is successfully completed, the funds are transferred to the customer's card with the next Paysafe batch run.

APIs to use: Payment Handles + Original Credits

Testing Instructions

Test Cards

You can use any of the following test card numbers to test the Paysafe Payments API.

Do not use real card numbers or other payment instrument details in the Test environment as it is not compliant with Payment Card Industry Data Security Standards (PCI-DSS), and does not protect card holder/payee information. Any upload of real cardholder data is strictly prohibited, as described in the Terms of Use.

Card Type Card Number 3D Secure Enabled Issuing Country
Visa 4530910000012345 No Canada
Visa 4510150000000321 No Canada
Visa 4500030000000004 Yes Canada
Visa 4003440000000007 Yes Canada
Visa 4515031000000005 Yes Canada
Visa 4538261230000003 Yes Canada
Visa 4037112233000001 No US
Visa 4037111111000000 Yes US
Mastercard 5191330000004415 No Canada
Mastercard 5457490000008763 No Canada
Mastercard 5258110000000005 Yes Canada
Mastercard 5192810000000009 Yes Canada
Mastercard 5100400000000000 No US
Mastercard 5200400000000009 Yes US

Expiry Date

When using the test card numbers, you can use any date in the future for the expiry date (e.g., 11/22).

CVV

You can use any 3-digit number for the CVV in the merchant Test environment. However, if you wish to generate a specific CVV match response, you will need to use the following values.

CVV Value CVV Response Code Description
111 MATCH Match
222 NOT_PROCESSED Not processed
555 UNKNOWN Unknown response
666 NO_MATCH No match

Simulating Authorization Responses

You can simulate the response to a card authorization request by specifying different amounts under $1.00 in the request. For regular testing, do not use amounts less than $1.00 (100 in minor units) as this will trigger different decline or delay cases.

Amount (Minor Units) HTTP Status Code Error Code Response
1 200 Approved
4 402 3015 The bank has requested that you process the transaction manually by calling the card holder's credit card company.
5 402 3009 Your request has been declined by the issuing bank.
6 500 1007 Clearing house timeout (although the simulator returns immediately; if delay is desired, see amount 96).
11 402 3022 The card has been declined due to insufficient funds.
12 402 3023 Your request has been declined by the issuing bank due to its proprietary card activity regulations.
13 402 3024 Your request has been declined because the issuing bank does not permit the transaction for this card.
20 500 1007 An internal error occurred.
23 402 4002 The transaction was declined by our Risk Management department.
24 402 3007 Your request has failed the AVS check.
25 402 4001 The card number or email address associated with this transaction is in our negative database.
90 200 Approved with 5-second delay
91 200 Approved with 10-second delay
92 200 Approved with 15-second delay
93 200 Approved with 20-second delay
94 200 Approved with 25-second delay
95 200 Approved with 30-second delay
96 500 1007 Declined with 35-second delay. Transaction timed out after 30 seconds.
100 200 Approved

3D Secure Results and Liability Shift

When 3D Secure is used in conjunction with an authorization request through the Payments API – requiring the customer to authenticate the card used in the transaction – a major advantage to the merchant is that with disputed payments the financial liability can shift from the merchant to the card issuer. Many factors affect whether this liability shift occurs, so merchants should contact their account manager for advice.

PARes Status Code Description Recommendation Note
Y Authentication successful Proceed with authorization Cardholder passed authentication
A Authentication attempted Proceed with authorization Liability shift in most cases
N Authentication failed Do not proceed with authorization Cardholder failed authentication
U Authentication unavailable Decision to proceed with authorization at merchant's discretion No liability shift
E Error Do not proceed with authorization No liability shift
Did you find this page useful?