Processing a payment with Direct Checkout

Overview

Processing a payment will involve the following steps:

• When your customer is ready to make a payment, you will need to send a Payment Intent request to the EPS endpoint
• Redirect the payer to your payment page and pass the information returned from the Payment Intent response into the Direct Checkout config object
• The payment page will be populated with the controls for selecting the payment method or collecting card details
• The payer selects their payment method and provides any requested detail
• The payer confirms or submits the payment
• Direct Checkout will process the payment request and return a response to the page
• You will then need to poll the EPS endpoint to confirm the outcome of the payment.

The lifelines (roles) in the diagram are described below:

Payment method specific processing

Information about processing for specific payment methods:

• Card.

Payment Intent

To create a payment intent, a request must be made to the Evolve Payment Service. You will need the details from Prerequisites to fulfil this request.

The example requests below shows the minimum data needed to successfully create a payment intent.

Pay only request

     curl --location --request POST '/api/v1/merchants/{ISV_ID}/transactions/payments' \
        --header 'jwt: {PAYMENT_ API_KEY}' \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "remittance": {
             "merchantId": "{BENEFICIARY_MERCHANT_ID}"
          },
           "paymentMethod": {
             "provider": "SBS",
             "methodId": "GATEWAY",
            "gateway": {
              "routing": "API"
             }
          },
          "transaction": {
              "amount": "9.87",
              "capture": true,
              "submit": false
          }
}'

• The “methodId” field in the request indicates the payment method to be used for processing the payment. The “GATEWAY” value indicates that the interfacing client (Direct Checkout in this case) is responsible for supplying the payment method chosen by the payer
• The “submit” field in the request indicates the creation of a payment intent. The value for this must always be “false”.
• The “routing” field must be set to “API” for Direct Checkout payments.
• The “remittance.merchantId” field should contain the identifier for the merchant that you are processing the payment for (the beneficiary of the payment).

Pay and store card request

You may store a card when submitting a card payment for authorisation.  The stored card can then be used when submitting a payment for authorisation.

Refer to the Stored Card Overview section for details on how stored cards may be used, and information on integrator responsibilities regarding agreement with cardholders.

Please note that currently you may only use stored cards to submit a Merchant Initiated Transaction (MIT); Customer Initiated Transactions (CITs) are not currently supported by Direct Checkout.

curl --location --request POST '/api/v1/merchants/{ISV_ID}/transactions/payments' \
--header 'jwt: {PAYMENT_ API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"remittance": {
		"merchantId": "{BENEFICIARY_MERCHANT_ID}"
},
	"paymentMethod": {
		"provider": "SBS",
		"methodId": "GATEWAY",
		"gateway": {
		"routing": "API"
		},
		"saveMethod": "YES"
	},
	"transaction": {
		"amount": "9.87",
		"capture": true,
		"submit": false,
		"recurring": "INITIAL",
		"recurringType": "CONTINUOUS"
	}
}

• “saveMethod” must be set to “YES”,  which means that card details will be automatically stored after authorisation, without asking the payer during the Direct Checkout transaction. 
• “recurring” must be set to “INITIAL” when storing a card.
• recurringType” may be either:
  • “CONTINUOUS” which indicates a merchant-initiated transaction (MIT) for a planned schedule of payments without an end date
  • “INSTALLMENT” which indicates a merchant-initiated transaction (MIT) for a fixed or planned schedule of payments with an end date.

Response

The response will contain the following:

• The request body
• Additional data identified based on the payment account
• Transaction related data that must be used to integrate into Direct Checkout:
• transaction.sessionId
• transaction.transactionId

Notes

• The transaction.sessionId is a JWT token, only valid for processing payments against the transaction.transactionId with a limited expiry
• The transaction.transactionId will be required to perform post-payment actions
• Refer to the API Reference for more information.

Collecting cardholder details

The payment intent request may optionally include shipping address, billing address and billing email fields, and this will need to match the implementation of the Cardholder Details component, as part of the Direct Checkout integration.  The options are as follows:

·       If you provide a shipping address and no billing address or billing email in the payment intent, display a checkbox to expand and show the billing address and email components (shown below).

·       If you provide neither a shipping address, nor a billing address or billing email in the payment intent, always display the billing address components (mandatory or all).

·       If you provide a billing address and billing email in the payment intent, the cardholder detail components are optional.

You will need to enter mandatory field data to proceed, and we provide validation and error messages for these fields.

Payment processing

The payment processing will take place after the payer confirms or submits the payment; for Apple Pay they Confirm via the Apple Pay payment sheet, and for Card they click on the Pay button.. Direct Checkout will submit the data from the browser to the Evolve Payment Service. Based on the validation performed on the payment data, Direct Checkout will return different actions:

• Payer required to perform 3D Secure (Card only)
• Payment successfully processed; without additional actions (3D Secure challenge is not required).
• Payment processing failed. This can cover many different scenarios such as card scheme not supported, acquirer decline or processing error.

Payer required to perform 3D Secure (Card only)

If 3D Secure is required, a challenge will be presented to the payer. This will be implicitly handled by Direct Checkout by displaying a full-page iframe with the card issuers challenge page loaded within.

After successfully completing the challenge, Direct Checkout will resume the payment processing.

Handle payment processing response

function callbackResponse(status, type,  response)

Parameters

Example

    function callbackResponse(status, type, response) {
    if (status === 'SUCCESS' && type === 'COMPLETE') {
        // payment success
    } else if (status === 'FAILED' && type === 'FAILED') {
        // payment failure
    } else if (status === 'FAILED' && type === 'UNAVAILABLE') {
        // payment failure due to service unavailable
    } else if (status === 'FAILED' && type === 'TIMED_OUT') {
        // payment failure due to session time out
    } else if (status === 'FAILED' && type === 'CANNOT_PROCEED') {
        // payment failure due to Apple Pay payment session creation failure        
    }
}
 

Checking payment outcome

After Direct Checkout has returned a callback response, you should notify your Integrator Service.

Since the Direct Checkout response has been returned to a public client (browser), you should verify the result by making a server-side call to the Evolve Payment Service. To do this, make a request to EPS to retrieve the payment status.

Request

  curl 
 --location 
 --request POST '  /api/v1/merchants/{ISV_ID}/transactions/payments/{TRANSACTION_ID}/query \ 
 --header 'jwt: {PAYMENT_API_KEY}' \           
 --header 'Content-Type: application/json'  \           
 --data-raw '{ 
   }' 
        

• The “transactionId” in the URL parameter must be the same as the value returned in the payment intent.

Response

The response will contain the following.

• The response body from the original payment intent.
• The result of the payment. The key fields are identified in the table below.

Pay and store card response

In addition to the fields described in the Response section above, the pay and store response will also contain details of the stored card, if a card was used.

Polling for an outcome

Since Direct Checkout is a browser-based payment solution, to mitigate against lost payments caused by network issues, you should implement a polling service to query the payment status. It is advisable to implement this to poll five minutes after the payment intent and then at regular intervals until the transaction.status is returned as either “COMPLETE” or “FAILED”.