|
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)
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 Host Payment Pages.
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": {
“returnUrl”: “integratersURL”
},
"saveMethod": "YES"
},
"transaction": {
"capture": true,
"submit": true,
"recurring": "INITIAL",
"recurringType": "CONTINUOUS"
}
}'
The Response will have a URL and the Merchange wiill have to redirect to the URL. The rest of the process will be handled - there's no further integration.
After Host Payment Pages has returned a callback response, you should notify your Integrator Service.
Since the Host 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.
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. |