Stored card for Direct Checkout

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 processed on a continuous, instalment, no show, or unscheduled basis. Continuous is for a series of transactions that that are processed at fixed, regular intervals. Installment 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 transactions without further cardholder involvement, such as in a continuous, instalment, unscheduled or no show 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 Direct Checkout – Pay and store card request section.

Payment using a stored card request

Please note that 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 '{{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"
        },
        "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 "CARD" for payment using a stored card when it is a merchant-initiated transaction (MIT).

paymentMethod.gateway.routing must be “API” for payment using a stored card.

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 Direct Checkout for information on payment processing, 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.

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

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": {
        "methodId": "GATEWAY",
        "gateway": {
            "acceptMethods": [
                "CARD"
            ],
            "routing": "API"
        },
        "saveMethod": "YES"
    },
    "transaction": {
        "submit": false,
        "recurring": "INITIAL",
        "recurringType": "INSTALLMENT",
        "continuousAuthorityAgreement": {
            "minFrequency": 28,
            "expiry": "2024-12-31",
            "numberOfInstalments": 12
        }
    }
}'

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

paymentMethod.gateway.routing must be “API” for Direct Checkout transactions.

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

transaction.submit must be false; this indicates that it is the creation of a Direct Checkout verify intent.

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

transaction.recurringType must 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 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*. Subsequent transactions can be processed as "UNSCHEDULED_CREDENTIALS_ON_FILE" or "NO_SHOW".

*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 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 transactions against the transaction.transactionId with a limited expiry

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

Refer to the API Reference Guide for more information.

Verify processing

The verify processing will take place after the cardholder clicks on the Verify button. Direct Checkout will submit the data from the browser to the Evolve Payment Service. Based on the validation performed on the data, Direct Checkout will return different actions:

• Cardholder required to perform 3D Secure.

• Verify successfully processed without additional actions (3D Secure challenge is not required).

• Verify processing failed. This can cover 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 verify processing.

Handle verify processing response

This covers both Verify successfully processed and Verify processing failed.

Upon verify processing completion by the Evolve Payment Service, a response will be returned to Direct Checkout with a status and a summary of the result. The response will trigger a JavaScript callback event to the function you defined in the config object in your integration. Rrefer to Initialise the library - Config object section. Based on the response received in the callback, you can perform the appropriate action.

function paymentCallback(status, type, response) 

Note that the function can be named anything you wish, we have used “paymentCallback” here as an example.

Parameters

Checking verify 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 verify status.

Request

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

Refer to Pay and store card request for information on PAYMENT_ENVIRONMENT, ISV_ID, and PAYMENT_API_KEY.

TRANSACTION_ID must be the same as the value returned in the verify intent.

Response

The response will contain the following:

• The response body from the original verify intent.

• The result of the verification. 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 Direct Checkout 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“.