Setup and process payment plan - Server to Server
Process an Initial payment
Step 1: Set the proper authentication details in the threeDs object when creating a Payment Handle during the Card Saving process:
- Set authenticationPurpose to RECURRING_TRANSACTION or PAYMENT_TRANSACTION.
- Set requestorChallengePreference to
- CHALLENGE_MANDATED for EU/UK issued cards, as the cardholders are mandatory to pass authentication challenge for establishing a payment plan.
- CHALLENGE_REQUESTED for cards that are issued outside of the EU/UK region, if you want the cardholders to pass authentication challenge. Although authentication may not be mandatory, it has the potential to improve the acceptance rate of the subsequent payments.
- Set the billingCycle with the necessary details. The field is required if authenticationPurpose is set to RECURRING_TRANSACTION.
- Fill in the other applicable details for the payment handle creation request and proceed with it.
Note that SCA exemptions cannot be used for establishment of recurring payment plan.
Step 2: Proceed with initial authorization, once the Payment Handle has been created successfully.
- Add the storedCredential object to the authorization with the appropriate type (RECURRING, TOPUP or ADHOC) and occurrence set to INITIAL to indicate the initial payment.
- Include the appropriate payment handle token.
- Fill in the other necessary details for the authorization request and proceed with it. If you receive a successful payment response, you must store the transaction ID in your back office, as you must supply it in the field initialTransactionId (storedCredential object) with each subsequent merchant-initiated rebilling for the same payment plan. The payment plan is established upon successful authorization request, and you can proceed to process a subsequent payment.
Process a Subsequent payment
Process Merchant-Initiated Credentials-On-File (RECURRING and TOPUP) transactions
- Initiate an authorization request to the Paysafe Payments API.
- Include the storedCredential object with the type (RECURRING or TOPUP), occurrence set to SUBSEQUENT and initialTransactionId.
- The initialTransactionId is the Paysafe transaction ID that was returned to you with the initial authorization confirmation.
- If the initial authorization was processed outside of Paysafe environment, you can supply the Scheme Transaction ID of the initial authorization in field externalInitialTransactionId.
- Include the multi-use payment handle token that was used for the creation of the payment plan from the Card Saving process.
- Fill in the other necessary details for the authorization request.
Process Adhoc Cardholder-Initiated Credentials-On-File transactions
Step 1: Proceed with creation of single-use Payment Handle created from multi-use Payment Handle.
- In the threeDs object:
- Set authenticationPurpose to PAYMENT_TRANSACTION.
- Set requestorChallengePreference to
- NO_PREFERENCE if you don’t have preference if the cardholder should be challenged or not.
- CHALLENGE_REQUESTED if you want the card issuing institution to challenge the cardholder authentication.
- Fill in the other necessary details for the request and proceed with it.
The authentication process may be skipped, if the card is issued in a non-regulated region or the one-leg out exception applies. However, the added security from the cardholder authentication can increase the chances of the subsequent transactions being approved.
Step 2: Proceed with an authorization with the newly created single-use Payment Handle:
- Include the storedCredential object with type ADHOC, occurrence set to SUBSEQUENT and initialTransactionId. The initialTransactionId is the Paysafe Transaction ID that was returned to you with the initial authorization confirmation.
If the initial authorization was processed outside of Paysafe environment, you can supply the Scheme Transaction ID of the initial authorization in field externalInitialTransactionId. - Include the single-use Payment Handle token.
- Fill in the other necessary details for the authorization request and proceed with it.