One-Time Card Payment using Maya Vault

Overview

Use the Maya Vault to tokenize the card details and secure the payment without using clear card details.

Do you prefer Maya's Checkout form?

Explore Maya Checkout for simple card acceptance without creating your payment form.

Use Maya Vault to perform the following:

  • Tokenize and secure the customer’s card details, and accept card payments without storing sensitive information on your platforms.
  • Initiate a singular payment transaction (If the customer decides not to save their cards)

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


API Sequence

Understand the API sequence and transaction flow of Maya Vault for one-time card payments.




  1. The customer fills out your hosted card form.
  2. Your platform (The API Consumer) sends the acquired card information to Maya’s Create Payment Token endpoint, to request card tokenization.
  3. Maya Vault encrypts and stores card details, generating a paymentTokenId to identify the vaulted card.
  4. Maya returns the paymentTokenId to your platform.
  5. Your platform initiates the payment using the paymentTokenId via the Create Payment endpoint.
  6. When Maya receives a Create Payment request, it will create a payment record with FOR_AUTHENTICATION status.
  7. Maya then responds with the payment details and the verificationUrl.
  8. Your platform redirects the customer to the verificationUrl obtained from the payment creation (Step 5).
  9. The customer complies and completes the verification process, based on the Issuing bank rules of their card.
  10. Once the transaction is authorized, Maya will process the payment and update the status of the payment record based on the result, either to PAYMENT_SUCCESS or PAYMENT_FAILED.
  11. Upon successful payment, Maya Vault will redirect the customer to your success page as provided in the redirectUrl during the payment creation (Step 5).
  12. Maya Vault sends a webhook notification to your platform.
  13. Your platform acknowledges the webhook payload and returns 200 OK. Please avoid processing complex logic before you reply to webhook to prevent timeouts.
  14. Your platform parses and processes the webhook payload.
  15. 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.

Design the required pages

Design and host your own forms and response web pages.

1. Create your Card Details form

Create a card details form for your customers to input their payment information, adhering to Maya Vault's specifications. Refer to the Create Payment Token for the required card information.

Is your platform PCI-DSS certified?

Do not store any card information (i.e. name, card number, expiry dates, CVV/CVC) on your application unless your platform is PCI-DSS certified.


2. Create your Response 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.

Tokenize Card Details

Tokenize customer’s card payment information via Maya Vault.


Tokenize the customer’s card payment information by calling the Create Payment Token endpoint. After a successful call, you'll receive a paymentTokenId. You will need this ID to create a payment.

Initiate Payment

Initiate a single payment transaction using the paymentTokenId.

Step 1: Create Payment

To complete the payment transaction, your application should call the Create Payment endpoint providing the following:

  • paymentTokenId from the Create Payment Token endpoint
  • all of the other required transaction details.

The Create Payment endpoint will return a verificationUrl.



Step 2: Redirect Customer to verificationUrl

Redirect the user to the verificationUrl to proceed with the card verification and complete the payment. This will prompt the customer for the 3DS authentication stage.

3DS authentication validation depends on the rules and processes of the customer's card-issuing bank.

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:

  1. How to create and configure your webhook
  2. Online payment errors

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


Endpoints

The following are the Maya Vault endpoints for the One-time Card Payment.

NameHTTP methodKey TypeEndpointsDescription
Create Payment TokenPOSTPUBLIC/payments/v1/payment-tokensTokenizes the card details and generates an equivalent paymentTokenId.
Create PaymentPOSTSECRET/payments/v1/paymentsCreates payment transactions using the card’s paymentTokenId and other payment details. It returns the transaction status and other details such as the paymentId, verificationUrl, etc.

Managing Payment Transactions
NameHTTP MethodKey TypeEndpointDescription
Retrieve Payment via IDGETSECRET/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 RRNGETSECRET/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 StatusGETPUBLIC/payments/v1/payments/{paymentId}/statusReturns the status of the payment identified by paymentId.
Cancel Payment via IDPOSTSECRET/payments/v1/payments/{paymentId}/cancelCancel 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

Can I reuse paymentTokenId?

Answer: No. paymentTokenId can only be used once per payment transaction. If the same payment details are used, you must generate a new paymentTokenId.