Pre-requisite: To pay using vaulted cards, it is important that you have implement either of the following:

Overview

Use vaulted cards for your customer's upcoming payments, providing a secure and enhanced payment experience.

Use vaulted cards to:

Enable customers to pay for future transactions with their saved cards.
Facilitate scheduled payments by creating your own recurring scheduler and utilizing vaulted cards.

Experience Maya Vault on our demo website (beta version) and test how it works using the Sandbox Credentials and Cards .

API Sequence

Learn the API sequence and transaction flow of Maya Vault for Pay using Vaulted Cards.

Customer opts to use their previously saved or vaulted cards for the payment.
Your platform (or the API Consumer) sends the transaction request to Maya Vault via the Create Customer Payment endpoint providing the customer's customerId and the cardTokenId of the chosen card.
Maya Vault processes the transaction given the details.
After successful processing, Maya Vault redirects the customer to the redirectUrl provided in Step 2.
Maya Vault sends a webhook notification to your platform.
Your platform acknowledges the webhook payload and returns 200 OK. Please avoid processing complex logic before you reply to webhook to avoid timeouts.
Your platform parses and processes the webhook payload.
Your platform notifies the customer of the updates of the transaction.

Build your Integration

This solution uses Basic Authentication, which requires API keys to authenticate incoming requests. To obtain your API key, please refer to the Generate API Keys for Online Payments guide.

Create your Response pages

Design and host your own response web pages.

Every payment state should show an appropriate web page for the customer to know the status of their transaction. You need to host these pages on your website.

Created URLs will be used in the redirectUrl object on the Create Customer Payment transaction request defining where the customer will be redirected when processing the transaction.

Use Vaulted Cards for Upcoming Payments

You can use the customer's vaulted card to pay for their future transactions.

For paying future transactions using the vaulted card, your application must call the Create Customer Payment endpoint. This step requires the following:

cardToken or the cardTokenId from the Create Card of Customer endpoint
customerId or the id acquired from the Create Customer endpoint
the necessary transaction details

Depending on the payment status, customers will be redirected according to the URL specified under the redirectUrl object of the Create Payment API.

🦉

Create Payment using Vault

Open Recipe

Monitor Real-time Transaction Events

Monitor and receive transaction updates.

Maya uses webhooks to inform your application about specific events related to payment requests. These notifications include the payment status and response codes.

Refer to the following resources to understand Webhooks and how to handle errors and declined payments:

If your application doesn't receive webhook notifications, use the following retrieve endpoints as an alternative:

Endpoints

The following are the Maya Vault API endpoints relevant for Paying using Vaulted Cards.

Name	HTTP Method	Key Type	Endpoint	Description
Create Customer Payment	POST	SECRET	/payments/v1/customers/{customerId} /cards/{cardToken}/payments	Initiates payments using the inputted `cardToken` (the selected vaulted card) as the payment source of the customer identified by the `customerId`.

Managing Payment Transactions

Name	HTTP Method	Key Type	Endpoint	Description
Retrieve Payment via ID	GET	SECRET	/payments/v1/payments/{paymentId}	Retrieves a comprehensive transaction details of the payment identified by the provided `paymentId`. This will yield an array containing the payment information.
Retrieve Payment via RRN	GET	SECRET	/payments/v1/payment-rrns/{rrn}	Retrieve transaction information by providing the merchant's request reference number (rrn), similar to the Retrieve Payment via ID endpoint.
Retrieve Payment Status	GET	PUBLIC	/payments/v1/payments/{paymentId}/status	Returns the status of the payment identified by `paymentId`.
Cancel Payment via ID	POST	SECRET	/payments/v1/payments/{paymentId}/cancel	Cancel a payment transaction using the `paymentId` before it's authorized and the card payment is completed.

Business Rules to Code

To supplement your knowledge of the integration, it is essential to familiarize the Business Rules to Code for Online Payments . This ensures that technology requirements and other development considerations are met.

At this point, you have understood the following:

The necessary APIs and their endpoints.
The sequence and purpose of each API.
The prerequisites in building your integration.

Frequently Asked

Will 3DS authentication be required when using a vaulted card?

Answer: It will only be asked during the first transaction of the customer. Contact your Maya Relationship Manager to learn more.

Can I build my recurring scheduler for payments?

Answer: Yes, you can create your scheduler and call Create Customer Payment according to your business rules.

Pay using Vaulted Cards