About Card Payments

The Paysafe Payments API supports Cards as a Payment Instrument. You can process credit cards, and debit cards and save or tokenize them on a Customer Profile to charge customers 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, Mastercard, Mastercard Debit (Maestro), Mastercard Prepaid, Discover.
• Transaction types: Payments, Refunds
• Payment authentication: Dynamic 3D Secure 2 (ready for Strong Customer Authentication)

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.

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.

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.

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.

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

For 3DS2 testing cards, see Test Cards.

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.

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.

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.

Account Name Inquiry (ANI) is a functionality provided by Visa that allows the verification of a cardholder's name against the name registered with the issuing bank. The check could be conducted prior to a transaction during consumer onboarding, immediately before a transaction, at regular intervals, or on an ad-hoc basis.

The last name is the minimum requirement to initiate an Account Name Inquiry (ANI). To enable a more comprehensive verification, including the first name will allow for a full name validation. By default, all transactions will have an Account Name Inquiry (ANI) response of a MATCH. To simulate a different response in the test environment, simply add a prefix code before the value entered for the last name, or both the first and last names.

Once the ANI outcome is received and the KYC decision is made, you can proceed with payments, standalone credits, or original credit requests. This ensures the consumer’s name has already passed an additional security check during onboarding and pre-transaction stages.

Note: The following values are applicable only for VISA transactions during Verification. 

Note: Account Name Inquiry (ANI) must be enabled before performing name verification. Contact Integration Support for further assistance. 

Click the buttons below to learn how to create a payment handle and validate a card.