Pay and Save a Card

Overview

Use the Maya Vault to tokenize card information and link a card to a customer, ensuring payment security without exposing clear card details, and improving the customer’s experience with card payments.

Leverage Maya Vault to perform the following:

  • Tokenize and vault the customer’s card details, without storing sensitive information on your platforms.
  • Save customer information and link cards to their owners, using their payment for card verification.
  • Use the tokenized and vaulted cards for future transactions.

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 and Save a Card.




  1. Customer inputs required details into your hosted form. This can be done during account creation or user registration on your website.
  2. Your platform (or the API Consumer) sends the customer information to Maya Vault via the Create Customer endpoint.
  3. Maya Vault stores the customer details and generates an id to identify the customer record uniquely.
  4. Maya Vault responds to your platform with the customer's id.
  5. Your platform saves the id which serves as the customerId on the succeeding steps/processes.
  6. The customer fills out your hosted card form.
  7. Your platform sends the card details to Maya Vault using the Create Payment Token endpoint.
  8. Maya encrypts the customer’s card details and generates the paymentTokenId.
  9. Maya returns the paymentTokenId to your platform.
  10. Your platform initiates a request to the Create Card of Customer endpoint to link the card using the paymentTokenId, to the customer identified by the customerId.
  11. Maya Vault links the paymentTokenId to the customerId and generates the cardTokenId.
  12. Maya Vault responds with the cardTokenId and the verificationUrl.
  13. Your platform saves the cardTokenId which serves as the cardToken in the future steps.
  14. Your platform initiates a request to the Create Customer Payment endpoint, to proceed with the customer’s payment.
  15. When Maya receives a Create Customer Payment request, it will create the payment record tagged as Pending
  16. Maya then responds with the payment details and verificationUrl.
  17. Your platform redirects the customer to the verificationUrl, obtained from the creation of the customer’s payment (Step 14).
  18. The customer complies and completes the verification process, based on the Issuing bank rules of their card.
  19. Maya Vault initiates card verification by processing the customer’s payment transaction.
  20. Upon successful card verification, Maya Vault will redirect the customer to your success page as provided in the redirectUrl during the payment creation (Step 14).
  21. Maya Vault sends a webhook notification to your platform.
  22. Your platform acknowledges the webhook payload and returns 200 OK. Please avoid processing complex logic before you reply to webhook to prevent timeouts.
  23. Your platform parses and processes the webhook payload.
  24. 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 Customer Information form

Design a form for customers to input their personal information as per Maya Vault requirements. This information can also be gathered through your application’s user registration or sign-up. Refer to the Create Customer for the required customer information.

2. 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.


3. 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 Card of Customer or on the Create Customer Payment transaction request defining where the customer will be redirected when processing the transaction.

Register a Customer

Create a customer record for attaching a fund source in Maya Vault, like a card linked to the customer.


Use the Create Customer endpoint to input acquired customer information into the Maya Vault. Once done, the API will provide an id, serving as the customerId for future steps.

Maya recommends that you keep the id of the customer record from the response. This id can be used to retrieve and manage customer details and card tokens.


Managing Customer Record

Maya Vault provides dedicated endpoints to assist in managing the customer record, allowing you to modify customer details, or delete the customer record:

Tokenize and Link the Card

Pay and vault the card

The customer pays for the transaction and vaults the customer’s card payment information in Maya Vault.

Step 1: Create Payment

Your application must call the Create Customer Payment endpoint to link the tokenized card details to the customer record. This step requires the following:

The Create Customer 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:

What's Next?

Once cards are successfully vaulted and linked to the customer, you can use them for future payments. For guidance, check out our guide on Pay using Vaulted Cards .


Endpoints

The following are Maya Vault API endpoints relevant for Pay and Save a Card.

NameHTTP MethodKey TypeEndpointDescription
Create CustomerPOSTSECRET/payments/v1/customersCreates a customer record for attaching a fund source, like a card linked to the customer. This endpoint generates an ID, which serves as the customerId.
Create Payment TokenPOSTPUBLIC/payments/v1/payment-tokens Tokenizes the card details and generates an equivalent paymentTokenId.
Create Card of CustomerPOSTSECRET/payments/v1/customers/{customerId}/cards Binds the card to the customer record using the paymentTokenId of the card and the customerId and generates a cardTokenId. This endpoint can be re-used to add more cards under a customer.
Create Customer PaymentPOSTSECRET/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. A successful transaction verifies and completes the card vaulting.

Managing Customer and their Cards
NameHTTP MethodKey TypeEndpointDescription
Retrieve CustomerGETSECRET/payments/v1/customers/{customerId}Returns the complete customer information using the customer’s customerId.
Update CustomerPUTSECRET/payments/v1/customers/{customerId}Modifies the information of an existing customer identified by a customerId. Returns the complete information of the modified customer record.
Delete CustomerDELETESECRET/payments/v1/customers/{customerId}Deletes the customer information identified by a customerId. Returns the complete information of the deleted customer record.
Retrieve Cards of CustomerGETSECRET/payments/v1/customers/{customerId}/cardsRetrieves all card tokens associated with the customer, representing the linked cards.
Retrieve a Card of CustomerGETSECRET/payments/v1/customers/{customerId}/cards/{cardToken}Get the specific card record for the customer using the cardTokenId (as cardToken) and customerId. This represents the linked card.
Update a Card of CustomerPUTSECRET/payments/v1/customers/{customerId}/cards/{cardToken}Sets the default card of a customer.
Delete a Card of CustomerDELETESECRET/payments/v1/customers/{customerId}/cards/{cardToken}Unlink a specific card associated with a customer using the cardTokenId (as cardToken). Upon a successful call, the cardTokenId will be deactivated/invalidated, and the complete card token information will be returned.
Managing Payment Transactions
NameHTTP MethodKey TypeEndpointDescription
Retrieve Payment via IDGETSECRET/payments/v1/payments/{paymentId}Retrieve the transaction information by providing the paymentId. The resulting response will be an array of the payment information.`.
Retrieve Payment via RRNGETSECRET/payments/v1/payment-rrns/{rrn}Retrieve the transaction information by providing the merchant’s request reference number. Functionality is similar to Retrieve Payment via ID, but instead of the paymentID, rrn is used.
Retrieve Payment StatusGETPUBLIC/payments/v1/payments/{paymentId}/statusBy providing the paymentId, use this API to get the payment status.
Cancel Payment via IDPOSTSECRET/payments/v1/payments/{paymentId}/cancelThis API is used to cancel a payment transaction by providing the paymentId; before it can be authenticated and card payment is made.


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

What’s the difference between Save a Card and Pay and Save integrations?

Answer:

In Save a Card , the customer's card information is vaulted without making a payment. The card is verified through a test charge of Php 10.

In Pay and Save, the customer's card details are stored while processing a payment. No test charge is needed as the payment itself verifies the card.

Can I use the stored user information in my application?

Answer: Yes, you may use the stored user information for your application. To access this data, simply utilize the retrieve customer endpoint providing the id.

Can I reuse paymentTokenId?

Answer: No. paymentTokenId can only be linked once. Attempts after successful linking to a customer will reject the request.

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. You could also refer to the Pay using Vaulted Cards for guidance.