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

Overview

Use Maya Vault to tokenize the customers' card details for their 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 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.
- If 3DS is not enabled for future transactions using vaulted cards, Maya Vault processes the transaction and responds with the transaction result to your platform.
- If 3DS is enabled for future transactions using vaulted cards:
  1. Maya Vault creates a payment record with status FOR_AUTHENTICATION
  2. Maya Vault responds with a verificationUrl to your platform.
  3. Your platform then redirects the user to the verificationUrl to complete 3DS authentication.
  4. The user complies and completes the 3DS authentication with Maya Vault.
  5. Maya Vault then redirects the user to the result pages or your redirectUrl provided in Step 2 (success, fail).
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 for 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.

Can I enable 3DS in payments using vaulted cards?

Answer: You may reach out to your Maya Relationship Manager to discuss and request turning on 3DS for future payments of vaulted cards. However, you will need to consider changes to the API Handling:

If 3DS is not enabled for future transactions using vaulted cards, Maya Vault will return the payment result.
If 3DS is enabled for future transactions using vaulted cards, Maya Vault will provide a verificationUrl, where you need to redirect the customer to complete the 3DS authentication. After completing the 3DS authentication, Maya Vault will redirect the customer to your result page.

Pay using Vaulted Cards