Card Payments for merchant shoppers

You will need to create a new customer or use an existing one. Please refer to the Merchant Shoppers API for details on how to create customer objects or fetch existing ones.

curl --location 'https://sandbox.api.getsafepay.com/user/customers/v1/' \
--data-raw '{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john-doe@gmail.com",
  "phone_number": "+923331234567",
  "country": "PK",
  "is_guest": true
}'

Note that there are no uniqueness constraints for emails when creating new customers. The customer token is the only unique identifier and we suggest persisting this in your system for future lookups.

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.

You must associate a customer to the tracker. The code samples below show how this can be achieved.

// For live payments use https://api.getsafepay.com
curl --location 'https://sandbox.api.getsafepay.com/order/payments/v3/' \
--data '{
  "merchant_api_key": "sec_ed8fa26a-e36d-49d2-89bd-1c72c8b5c133",
  "user" : "cus_e927d58d-3796-4f36-a209-384906d712ea",
  "intent": "CYBERSOURCE",
  "mode": "payment",
  "currency": "PKR",
  "amount": 100000
}'

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. For server-to-server requests, you may authenticate using your secret key.

You must provide your customer's payment method details to perform a payment. There are several ways to collect this information from the customer.

Cybersource Flex Microform

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.

curl --location 'https://sandbox.api.getsafepay.com/order/payments/v3/track_dccdef16-008e-4fae-81cc-1b7d81bf6c44' \
--data '{
  "payload": {
    "origin": "https://api-example.com"
  }
}'

The capture context also specifies a target origin for which it is valid. By default, this is set to Safepay Checkout. However, this may be modified by passing the origin as shown above.

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.

curl --location 'https://sandbox.api.getsafepay.com/order/payments/v3/track_dccdef16-008e-4fae-81cc-1b7d81bf6c44' \
--data '{
  "payload": {
    "payment_method": {
      "flex": {
        "transient_token_jwt": "eyJraWQiOiIwOGlUMXJQYkFCMGliTXdBYzduMmVLd3lwZFVsWWszZiIsImFsZyI6IlJTMjU2In0.eyJkYXRhIjp7ImV4cGlyYXRpb25ZZWFyIjoiMjAyMyIsIm51bWJlciI6IjUyMDAwMFhYWFhYWDEwOTYiLCJleHBpcmF0aW9uTW9udGgiOiIxMiIsInR5cGUiOiIwMDIifSwiaXNzIjoiRmxleC8wOCIsImV4cCI6MTY5NjYxODI1MCwidHlwZSI6Im1mLTAuMTEuMCIsImlhdCI6MTY5NjYxNzM1MCwianRpIjoiMUU1NlhTNEY1S0VCUVE4TTZIOE0wTlc1SVI4QjdKS0VZTjdPVVU5NTc5TVIwVFk1U1FLRTY1MjA1NzBBQUIxMyIsImNvbnRlbnQiOnsicGF5bWVudEluZm9ybWF0aW9uIjp7ImNhcmQiOnsiZXhwaXJhdGlvblllYXIiOnsidmFsdWUiOiIyMDIzIn0sIm51bWJlciI6eyJtYXNrZWRWYWx1ZSI6IlhYWFhYWFhYWFhYWDEwOTYiLCJiaW4iOiI1MjAwMDAifSwic2VjdXJpdHlDb2RlIjp7fSwiZXhwaXJhdGlvbk1vbnRoIjp7InZhbHVlIjoiMTIifSwidHlwZSI6eyJ2YWx1ZSI6IjAwMiJ9fX19fQ.UXynZWMX-269Okkq6me3sCkqorfSJEA_U634-GaDRfZUhQCJ-c7RZIW6pzB-Du1v1-MaRwAN8K_HZnDrjnmwsUw3bQGpqCSYRnwPU9oNURkoWiTm5bZu1PtRuGgid3UvZ77C7fPV_8NHqxLv9WRx6W_QYYk0J9xKulql6PVFDS0Mmpew0tkQfKlGda8u995seV24OPJa7UOp0oWzaJYMmrEP9HoGwQJo2EKYpIko_9eqaKxFQDJ9VOG64IdfIR0NxpCiKGL9Yyf9V5RRZclM0BFu8CvFTmpGW4890haE0yINapgg7mfjUMDewk803zacnNuRLTueMvy2l4DE8NGxag"
      }
    }
  }
}'

Raw payment method information

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.

To begin payer authentication, make a POST payerAuthSetup request to perform the PAYER_AUTH_SETUP action. If the tracker has the raw payment 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 may skip ahead to Enrollment.

curl --location 'https://sandbox.api.getsafepay.com/order/payments/v3/track_dccdef16-008e-4fae-81cc-1b7d81bf6c44' \
--data '{
  "payload": {
    "payment_method": {
      "card": {
        "card_number": "5200000000001096",
        "expiration_month": "12",
        "expiration_year": "2028",
        "cvv": "123"
      }
    }
  }
}'

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 to the Enrollment request.

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.

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.

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.

curl --location 'https://sandbox.api.getsafepay.com/order/payments/v3/track_dccdef16-008e-4fae-81cc-1b7d81bf6c44' \
--data '{
  "payload": {
    "billing": {
      "street_1": "St 1",
      "street_2": "",
      "city": "Islamabad",
      "state": "",
      "postal_code": "44000",
      "country": "PK"
    },
    "authorization": {
      "do_capture": false
    },
    "authentication_setup": {
      "success_url": "https://sandbox.api.getsafepay.com/checkout/success",
      "failure_url": "https://sandbox.api.getsafepay.com/checkout/failure",
      "device_fingerprint_session_id": "daf7d3a7-3a06-417b-af7b-c62d8d57493b"
    }
  }
}'

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. Here is how to interpret the enrollment response:

The response will also yield an authentication_status field that may take the following values. Here is how to interpret these:

The values for eci or eci_raw denote whether enrollment was successful:

More details for 3DS payer authentication can be found here.

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 Capture.

Authorization must be requested for frictionless 3DS payments i.e. when no challenge is issued. 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.

curl --location 'https://sandbox.api.getsafepay.com/order/payments/v3/track_dccdef16-008e-4fae-81cc-1b7d81bf6c44' \
--data '{
  "payload": {
    "authorization": {
      "do_capture": false
    }
  }
}'

Make a POST capture request to perform the CAPTURE action. If successful, the payment will have been captured.

curl --location 'https://sandbox.api.getsafepay.com/order/payments/v3/track_dccdef16-008e-4fae-81cc-1b7d81bf6c44' \
--data '{}'