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 cardholder to your payment page and pass the information returned from this request into the Direct Checkout payment method.
• The payment page will be populated with the appropriate controls for taking the cardholder information.
• The cardholder fills in their details and submits the payment.
• Direct Checkout will process the payment request, including any 3D Secure challenges, 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 Intent

To create a payment intent, a request must be made to the Evolve Payment Service. You will need the details from the Pre-requisites section above 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 selected payment method (currently only card is supported).
• 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

For DC, 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

For HPP, the response will have a URL and the Merchant wiill have to redirect to the URL. The rest of the process will be handled - there's no further integration.

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 data

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 clicks 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
• 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

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 paymentCallback(status, type,  response)

Parameters

Example

function paymentCallback(status, type,  response) { 

            const transactionType = response?.data?.summary?.type; 

            if (status === 'SUCCESS' && type === 'COMPLETE') { 

            // payment success 

            } else if (status === 'FAILED' && type === 'FAILED') { 

            // payment failure 

            } else if (status === 'FAILED' && type === 'UNAVAILABLE') { 

            // system unavailable 

            } else if (status === 'FAILED' && type === 'TIMED_OUT') { 

            // payment timeout 

            } 

            } 

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