Processing a payment with Hosted Payment Pages

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 customer to the URL returned in the Payment Intent response
• We will collect the information returned from this request
• We will process the payment request, including any 3D Secure challenges. We will redirect back to you on payment completion
• 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:

Customer	The payer that is making a payment through Hosted Payment Pages.
Browser	The HTML page on the Integrator’s domain that the payer has been redirected to by the Integrator Server.
Browser Hosted Payment Pages	The HTML page on the Access PaySuite domain that has been loaded by the Hosted Payment Pages library within an iframe to securely capture payment data.
Browser Card Issuer	The HTML page on the Card Issuer domain that has been loaded by the Hosted Payment Pages library within an iframe to securely capture a 3D Secure challenge.
Integrator Server	The Integrator server that is making the server-side calls to the Evolve Payment Platform and handling the interaction between their payment page that contains Hosted Payment Pages.
Evolve Payment Platform	The Evolve Payment service.
Acquirer	The Acquiring bank used to process payments.

 

Payment Intent

To create a payment intent, a request must be made to the Evolve Payment Service. You will need the details from the Prerequisites page 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": {
            “returnUrl”:  “integratersURL” 
             }
          },
          "transaction": {
              "amount": "9.87",
              "capture": true,
              "submit": true
          }
}'

• 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 (Hosted Payment Pages 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 of this should be true so that the Hosted Payment Pages session is automatically created with a URL to redirect to
• The “routing” field is not required but if used must be set to “HOSTED” for Hosted Payment Pages 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 also supported by Hosted Payment Pages.

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": {
		"returnUrl": "integratersURL"
		},
		"saveMethod": "YES"
	},
	"transaction": {
		"amount": "9.87",
		"capture": true,
		"submit": true,
		"recurring": "INITIAL",
		"recurringType": "CONTINUOUS"
	}
}

• “saveMethod” must be set to “YES”, or "ASK",  if YES, it means that card details will be automatically stored after authorisation, without asking the payer during the Hosted Payment Pages transaction.  . If ASK, then the payer will be prompted to agree the storage of the card.
• “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.
  •  "CREDENTIALS_ON_FILE" to process CIT payments

Response

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

Checking Payment Outcome

The Hosted pages will redirect to the Integrator (as per the returnUrl in the payment intent). Since the Hosted Payment Pages 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.

Field	Description
transaction.status	Indicates the status of the transaction processing. "COMPLETE" – transaction processing complete "FAILED" – transaction processing failed
paymentMethod.providerResponse.result	Indicates the result of the transaction. “AUTHORISED” “DECLINED” “FAILED”
paymentMethod.card.authCode	For a successful card payment, the authorisation code returned by the acquirer
paymentMethod.card.cardScheme	For a successful card payment, the card scheme used to process the payment (Visa or MasterCard)

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.

Field	Description
paymentMethod.storedMethod.token	A token for the stored card, to be used in future transactions
paymentMethod.storedMethod.verification	The last four digits of the stored card, to assist with identifying and validating the token

Polling for an outcome

Since Hosted Payment Pages 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”.