Learn how you can use the Safepay Order API to take your customer through the payment method tokenization journey.
The payment method tokenization journey for your customer involves a few key steps. This guide pertains to Safepay shoppers i.e. shoppers who have an account on the Safepay network.
Note that Safepay shopper APIs are currently reserved for internal use until a secure mechanism is introduced for facilitating the creation of user passwords. If you wish to make use of these APIs, please reach out to us on integrations@getsafepay.com.
To commence and successfully conclude the payment method tokenization journey, you will require the following items.
1
Create a new tracker. Make a POST setupPayment request to Safepay. This request is ideally made server-side and the tracker token may be passed to the client side where it may later be fetched using the fetchPayment API.
Note that the Tracker must be created in instrument mode. For more information, please follow the modes documentation.
2
Create a token for authenticating your server-side requests as a merchant. For security, we recommend creating a time based token server-side and then using that to authenticate when calling Safepay APIs from the frontend.
3
Create a token for authenticating your requests from the frontend as a Safepay shopper. Safepay uses shopper authentication to perform certain actions that require customer contact details. If you do not have a Safepay shopper, you may create one.
Depending on your flow, you may also want to determine if a Safepay shopper exists against the email that your customer has provided. You may make use of the Safepay shopper exists API to do this.
1
You must provide your customer's payment method details in order to tokenize them. There are several ways to collect this information from the customer.
The flex microform is a set of card fields hosted on Cybersource that are used to capture the customer's card details. You would embed the flex fields into your UI where the customer can enter their card information.
To integrate the flex microform your tracker must have the flex payment entry mode. Then you would make a POST generateCaptureContext request to perform the GENERATE_CAPTURE_CONTEXT action. You must also specify your domain as the origin so that the micoroform may render properly.
For more details on how to generate the form, please refer to the Microform guide. Specifically, you should refer to the Client Side documentation. This process should help you obtain the transient token JWT from the card fields which you will require for the next action. The transient token identifies the customer's card and may be used to complete the rest of the flow.
Once the transient token JWT is received, you must make a POST processTransientToken request to perform the PROCESS_TRANSIENT_TOKEN and PAYER_AUTHENTICATION_SETUP actions. The response for this yields the card details along with the payer_authentication_setup object which carries the access_token and the device_data_collection_url. These are necessary for collecting the user's device data and passing the resulting fingerprint in the enrollment step.
You may host input fields on your UI to capture the customer's payment method details.
For cards, you must be PCI compliant to be able to do this. Safepay will require your PCI certificate before we can enable payments for this entry mode.
To submit payment method details in plaintext, the tracker must have the raw payment entry mode. For this flow you may skip ahead to Payer Authentication.
For more details, please refer to Payment Modes
For security, the customer must authenticate themselves with the issuing bank via 3-D Secure. You may use Safepay APIs in conjunction with Cybersource 3-D Secure to take your customer through the payer authentication process. For more information, you may refer to our Payer Authentication guide.
2
To begin payer authentication, make a POST payerAuthSetup request to perform the PAYER_AUTH_SETUP action. If the tracker has the raw entry mode set, you must pass the payment method details in the request as documented in the API reference examples. Note that if you are following the Flex Microform flow then this would have already happened during the processTransientToken call and you can skip ahead to Enrollment.
The response for this action yields the card details along with the payer_authentication_setup object which carries the access_token and the device_data_collection_url. These are necessary for collecting the user's device data and passing the resulting fingerprint in the Enrollment request.
3
Next you will need to collect your customer's device data. This process is documented here. You will need the access_token and device_data_collection_url from the previous step.
4
Make a POST payerAuthEnrollment request to perform the PAYER_AUTH_ENROLLMENT action. You must pass the device_fingerprint_session_id obtained after device data collection to ensure liability shift. The customer's billing details and authorization options are also configured in this request. For authentication, you would pass the Safepay shopper's JWT.
You must also specify return URLs for success and failure scenarios in this request. These are URLs that the customer is redirected to after the step up process is complete.
If enrollment is successful, you should obtain the appropriate ECI values and the access_token in the payer_authentication_enrollment object. If the step_up_url is present, you should redirect the user and present the challenge screen from the issuer.
If the step-up_url is missing and the value for veres_enrolled is U, then it means that the card is not enrolled in 3DS. You may want to halt the payment flow at this point and display an error to the customer.
5
Initiate step-up authentication on your front-end using the access_token and step_up_url obtained from the previous step. This is documented here. The customer authenticates themselves with the issuing bank and then is redirected to the success_url or failure_url depending on the result.
If payer authentication is successful, the PAYER_AUTH_VALIDATION action would already have been performed and the payment would be authorized. You may proceed to Reversal.
6
Authorization must be requested for frictionless 3DS payments. It may also be requested to bypass payer authentication although this is not recommended and not possible across all card payment providers on Safepay.
Make a POST authorize request to perform the AUTHORIZATION action. Note that this will also perform the reversal action in the same request.
7
Performing an authorization is necessary in order to save a payment method. However, the hold on the customer's amount must be removed by performing an authorization reversal.
Make a POST reversal request to perform the REVERSAL action. If successful, the authorization will have been reversed.