Stored Card for Hosted Pages

Overview

You may store a card either when submitting a payment for authorisation, or when verifying that card. The stored card can then be used when submitting a payment for authorisation.

Stored card payments may be cardholder initiated, or processed on a continuous, instalment, or unscheduled basis. Continuous is for a series of transactions that that are processed at fixed, regular intervals. Instalment is for two or more transactions over a period for a single purchase of goods or services. No show is for charging the cardholder a penalty according to the merchant’s cancellation policy. Unscheduled is for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date.

The first payment or verify request must be flagged as an initial transaction and payment requests using a stored card must be flagged as subsequent. For continuous and instalment transactions, additional information about the agreement must be provided in the initial request.

Continuous and instalment payment types must be initiated and managed by the merchant along with any scheduling logic associated with these types of transactions.

Agreement with the cardholder

Integrators are responsible for ensuring that they establish a clear agreement with cardholders as to when their payment credentials will be stored, and how and when they may be reused.

The Stored Credentials Framework for Visa and Mastercard, and EMV 3DS, specifies that when an integrator processes a transaction and stores payment credentials for later use, they must:

• Establish a clear agreement with the cardholder for the storage and use of these payment credentials.

• Obtain consent for the storage of payment credentials for reuse.

• If the integrator is going to initiate transactions using these details without involving the cardholder, confirm the basis on which this will be done.

• Describe how the cardholder can seek to change the agreement, or how the integrator will contact the cardholder to do so.

• Indicate when the agreement will expire, if applicable.

• Indicate (as part of the transaction authorisation) that the payment credentials are being stored for future reuse.

• For initial continuous and instalment transactions, provide Continuous Authority Agreement information in the request.

• When a transaction is processed using stored payment credentials, indicate that existing stored credentials are being reused in the transaction authorisation.

This applies when the integrator will use the stored payment credentials to process customer initiated transactions, and transactions without further cardholder involvement, such as in a continuous, instalment or unscheduled transaction. The implicit storage of payment credentials to facilitate refunds is not considered “storage” for the purpose of this mandate; a payment credential is considered to be reused only when it is used to process a new payment transaction or account verification.

Pay and store card request

Refer to Processing a payment with Hosted Pages Pay and store card request section.

Payment using a stored card request

curl --location --request POST '{{PAYMENT_ENVIRONMENT}}/api/v1/merchants/{{ISV_ID}}/transactions/payments \
--header 'jwt: {{PAYMENT_API_KEY}}' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{
    "remittance": {
        "merchantId": "{{MERCHANT_ID}}"
    },
    "paymentMethod": {
        "provider": "SBS",
        "methodId": "CARD",
        "gateway": {
            "routing": "API",
            "returnUrl": "{{RETURN_URL}}"
        },
        "storedMethod": {
            "token": "{{TOKEN}}",
            "verification": "{{VERIFICATION}}"
        }
    },
    "transaction": {
        "amount": "10.00",
        "capture": true,
        "submit": true,
        "recurring": "SUBSEQUENT",
        "recurringType": "CONTINUOUS"
    }
}' 

PAYMENT_ENVIRONMENT is the Sandbox or Production environment for payment tasks.

ISV_ID is the identifier for the integrator.

PAYMENT_API_KEY is the API key for payment endpoints.

MERCHANT_ID is the identifier for the merchant that you are processing the payment for - the beneficiary of the payment.

paymentMethod.methodId must be either:

• “CARD” when recurringType is CONTINUOUS, INSTALLMENT or UNSCHEDULED_CREDENTIALS_ON_FILE. These are merchant-initiated transactions (MITs)

• "GATEWAY" when recurringType is CREDENTIALS_ON_FILE. This is a cardholder-initiated transaction (CIT).

paymentMethod.gateway.routing is conditional and defaults to “HOSTED”, however it:

• must be “API”  when recurringType is CONTINUOUS, INSTALLMENT or UNSCHEDULED_CREDENTIALS_ON_FILE. These are merchant-initiated transactions (MITs)

• is recommended to include it as “HOSTED” when recurringType is CREDENTIALS_ON_FILE.

TOKEN and VERIFICATION are provided in the initial payment or verify response.

transaction.capture must be true for payment using a stored card.

transaction.submit must be true for payment using a stored card.

transaction.recurring must be “SUBSEQUENT” when using a previously stored card.

transaction.recurringType must match the value used for the initial card storage, unless otherwise indicated, and be either:

• “CONTINUOUS” for a planned schedule of payments without an end date*

• “INSTALLMENT” for a fixed or planned schedule of payments with an end date*

• “UNSCHEDULED_CREDENTIALS_ON_FILE” for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date*

• “NO_SHOW” for charging the cardholder a penalty according to the merchant’s cancellation policy*. The initial value would have been "UNSCHEDULED_CREDENTIALS_ON_FILE".

*Use of the stored card will be a merchant-initiated transaction (MIT).

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 with Direct Checkout:

  • transaction.sessionId is a JWT token, only valid for processing payments against the transaction.transactionId with a limited expiry

  • transaction.transactionId will be required to perform post-request actions.

Refer to API Reference Guide for more information.

Refer to Processing a payment with Hosted Pages for information on checking payment outcome, cardholder information text, and polling for an outcome.

Verify intent

You may store a card when verifying that card, so no payment is processed. The stored card can then be used when submitting a payment for authorisation.

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

Verify and store card request

curl --location --request POST '{{PAYMENT_ENVIRONMENT}}/api/v1/merchants/{{ISV_ID}}/transactions/verify \ 
--header 'jwt: {{PAYMENT_API_KEY}}' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{
    "paymentMethod": {
        "provider": "SBS",
        "methodId": "GATEWAY",
        "gateway": {
            "routing": "HOSTED",
            "returnUrl": "{{RETURN_URL}}"
        },
        "saveMethod": "YES"
    },
    "transaction": {
        "submit": true,
        "recurring": "INITIAL",
        "recurringType": "INSTALLMENT",
        "continuousAuthorityAgreement": {
            "minFrequency": 28,
            "expiry": "2024-12-31",
            "numberOfInstalments": 12
        }
    }
}'

Refer to Payment using a stored card request for information on PAYMENT_ENVIRONMENT, ISV_ID, PAYMENT_API_KEY, and MERCHANT_ID.

paymentMethod.gateway.routing is conditional and defaults to “HOSTED”, however it is recommended to include this for Hosted Pages transactions.

paymentMethod.saveMethod must be “YES”, so that card details will be automatically stored after successful authorisation.

transaction.submit must be true; this indicates that it is the creation of a Hosted Pages payment intent.

transaction.recurring must be “INITIAL” when storing a card.

transaction.recurringType must be one of:

• “CONTINUOUS” for a planned schedule of payments without an end date*

• "CREDENTIALS_ON FILE" for storage and use of a card so a cardholder can initiate a payment without entering their card details

• “INSTALLMENT” for a fixed or planned schedule of payments with an end date*

• “UNSCHEDULED_CREDENTIALS_ON_FILE” for merchants who will initiate one or more future transactions for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date*.

*Use of the stored card will be a merchant-initiated transaction (MIT).

transaction.continuousAuthorityAgreement.minFrequency must be specified for initial CONTINUOUS and INSTALLMENT transactions, and is the minimum number of days between payments in the continuous or instalment sequence.

transaction.continuousAuthorityAgreement.expiry must be specified for initial CONTINUOUS and INSTALLMENT transactions, and is the date at which the continuous or instalment agreement expires or will need to be re-authenticated in order to continue.

transaction.continuousAuthorityAgreement.numberOfInstalments must be specified for initial INSTALLMENT transactions, and is the total number of payments in an instalment sequence (including this one, as starting with a payment). An instalment sequence must consist of two or more payments.

Response

The response will have a URL and the Merchant should be redirected to the URL. The card data entry and processing will be handled by Evolve.

Checking verify outcome

Hosted Pages will redirect to the Integrator as per the paymentMethod.gateway.returnUrl in the verify intent. Since the Hosted 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 verify status.

Request

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

{{TRANSACTION_ID}} should be the same as the value returned in the payment intent.

Response

The response will contain the following.

• The response body from the original verify intent.

• The result of the verify. The key fields are identified in the table below.

Cardholder information text

Merchants must display cardholder information text, when it is provided by card issuers. If provided, this will be in paymentMethod.card.threeDSResult.cardholderInfo.

The purpose of the text is to enhance the EMV 3DS experience, where the issuer can give the cardholder a call to action following the transaction.

Visa provide user-tested guidelines on how to properly display the text to the cardholder here.

Polling for an outcome

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