|
You may store a card either when submitting a payment for authorisation, or when verifying that card (no payment is processed). The stored card can then be used when submitting a payment for authorisation.
Card payments may be taken on a continuous or instalment basis. For example, a subscription for goods or services would require continuous payments, whereas paying off a loan would be done with instalments.
The first payment or verify request needs to be flagged as an initial transaction and the subsequent payment requests will need to reference the original transaction.
Continuous and instalment payment types must be initiated and managed by the merchant along with any scheduling logic associated with these types of transactions.
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 specifies that when an integrator processes a transaction and stores payment credentials for later use, they must:
This applies when the integrator will use the stored payment credentials to process transactions without further cardholder involvement, such as in a continuous or instalment transactions.
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.
Refer to Payment intent – Pay and store card request section.
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.
Call 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": "CARD",
"storedMethod": {
"token": "{TOKEN}",
"verification": "{VERIFICATION}"
}
},
"transaction": {
"amount": "9.87",
"capture": true,
"submit": true,
"recurring": "SUBSEQUENT",
"recurringType": "CONTINUOUS"
}
}'
Refer to Payment Intent – Response section.
You may store a card when verifying that card (no payment is processed). The stored card can then be used when submitting a payment for authorisation.
Refer to the Overview section above 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/verify \
--header 'jwt: {PAYMENT_ API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"paymentMethod": {
"provider": "SBS",
"methodId": "GATEWAY",
"gateway": {
"routing": "API"
},
"saveMethod": "YES"
},
"transaction": {
"capture": true,
"submit": false,
"recurring": "INITIAL",
"recurringType": "CONTINUOUS"
}
}'
The response will contain the following:
The verify processing will take place after the payer 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 payment data, Direct Checkout will return different actions:
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.
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 (refer to Initialise Direct Checkout section above).
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.
| Parameter | Description |
|---|---|
| status |
This returns the status of the transaction.
The possible values are:
|
| type |
This indicates more information about the transaction status.
The possible values are:
|
response |
This contains the response of processing the transaction and is based on the status parameter.
The response object will either have:
|
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.
curl --location --request POST ' /api/v1/merchants/{ISV_ID}/transactions/verify/{TRANSACTION_ID}/status' \
--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 verify intent.
| Field | Description |
|---|---|
| transaction.status |
Indicates the status of the verification processing:
|
| paymentMethod.providerResponse.result |
Indicates the result of the verification:
|
paymentMethod.storeMethod.token | For a successful verification, the token created to enable subsequent payments to be processed. |
| paymentMethod.storeMethod.verification | For a successful verification, the last four digits of the card used to process the payment. This will be required when processing subsequent payments. |
| paymentMethod.card.cardScheme | For a successful card payment, the card scheme used to process the payment (Visa or MasterCard). |
| card.expiryMonth | For a successful verification, the expiry month of the card. Useful to request future verifications when the card expires. |
| card.expiryYear | For a successful verification, the expiry year of the card. Useful to request future verifications when the card expires. |