Pay and Save a Card
Maya Card Payment Vault allows merchants to securely store a customer's card details after purchase
Go to our demo website (beta version) and see how Vault works.
How Maya Vault Works
Use the generated unique token depending on your target user journey within your application or website.
Expand this section to learn more
Customer Journey
Key Features
Vaulted Cards for On-Demand Payments ⭐️
Recommended by most of Maya’s Partners! Store your customer’s payment credentials securely in Maya Card Payment Vault and use the unique token in making payments at your own scheduling.
Learn more →Secure Card Tokenization for One-time Card Payment
A secure way on handling card information by using unique card token in making a single payment.
Learn more →Available SDKs
You can also accept payments in your UI by using Maya’s SDKs:
Become a partner
Technical Guide
1 Setup Maya Business Manager
Contact your assigned Relationship Manager to gain access to your Maya Manager Sandbox account. If you don't have any Relationship Manager, you may email [email protected] to assign one.
Keep in mind
Maya Manager has two environments: Sandbox and Production.
- Sandbox is used for development, testing, and integration. Once the integration is completed in this environment, it will be verified by our Operations team. Only then the production credentials will be provided.
- Production is for live payments. Testing in this environment will incur real charges.
Both environments have the ability to generate API keys. Once your account is onboarded to a sandbox account, you need to log in to the manager account of your respective environment.
2 Generating API Keys and API Authentication
Generate your API keys by following the steps below:
Step 1: Login to Maya Manager Sandbox and generate your API Key.
Step 2: Go to the menu on the left side of the screen and look for API Keys.
Step 3: On the main navigation, select the name of the Merchant that you registered earlier. Then generate the API key by clicking Generate API Key.
Step 4: After being redirected to another screen, create keys for both Public and Secret policies.
Step 5: Click Create then your API key will be shown to you.
The same flow will be used when generating keys on to your Production environment.
Save your API key in a secured location
The full API key will only be shown once. It is important that you store it in a secure location. If you lost your API key, try generating it again using the environment you are working on.
Authenticating with our API
Authentication is done via HTTP Basic Authentication. Depending on the API endpoint, the public (pk-....) or secret (sk-....) key must be provided as the username and the password left as blank.
Steps are as follows:
- Combine Username and Password (left blank) separated by ‘:’ (colon). If your API key is “pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah”, the resulting string is:
pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah:
- Apply Base64 encoding to the resulting string from Step 1. Using the resulting string from Step 1, the Base64 encoded string will be:
cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
- Indicate the authorization method i.e. “Basic” followed by a space then the Base64 encoded string in Step 2. An example is shown below.
Authorization: Basic cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
See also: HTTP Basic Auth
3 Prepare required pages for Vault
Every payment state should show an appropriate web page in order for the customer to know the status of their transaction. You need to host these pages in your website.
Click here to see sample pages
Credit Card Form Sample
<html>
<head>
<title>Credit Card</title>
</head>
<body>
<form action="/submit-credit-card" method="POST">
<input class="cn" placeholder="Card number">
<input class="date" placeholder="MM / YY">
<input class="cvc" placeholder="CVC" type="password">
<button type="submit">Submit</button>
</form>
</body>
</html>
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.
Success Page Sample
<html>
<head><title>Payment is successful</title></head>
<body>
<h1>Thank your for your order!</h1>
<p>
<a link="/track-order">Tracker your order here</a>.
</p>
</body>
</html>
Failed Page Sample
<html>
<head><title>Payment Failed</title></head>
<body>
<h1>Payment Failed!</h1>
<p>
<a link="/track-order">Create a new order?</a>.
</p>
</body>
</html>
Cancelled Page Sample
<html>
<head><title>Cart</title></head>
<body>
<h1>List of items inside the cart</h1>
<p>
<a link="/track-order">Checkout</a>.
</p>
</body>
</html>
4 Pay and save the card for future transaction
4.1 Register a customer in Maya Vault
Register the customer details to Maya Vault by sending the required customer information to the Create Customer API.
Sample request data:
{
"contact": {
"phone": "123456"
},
"billingAddress": {
"countryCode": "PH"
},
"shippingAddress": {
"countryCode": "PH"
},
"firstName": "John",
"lastName": "Doe"
}
The Create Customer API endpoint will return an id in the response which you will need on the succeeding steps.
Maya recommends that you keep the
idof the customer record from the response. Thisidcan be used to retrieve customer details and card tokens.
FAQ: Can I use the stored user information in my own application?
Answer: Yes, you may use the stored user information for your own application.
4.2 Tokenize the card details
Once the customer has provided their card details, your system must send this information to Maya Vault’s Create Payment Token endpoint.
Sample request data:
{
"card": {
"number": "512345678911",
"expMonth": "8",
"expYear": "2025",
"cvc": "111"
}
}
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.
The Create Payment Token endpoint will return a paymentTokenId. You will need to use this paymentTokenId to associate the tokenized card information with your customer.
FAQ: Can I reuse
paymentTokenId?Answer: No.
paymentTokenIdcan only be linked once. Attempts after successful link will reject the request.
4.3 Link tokenized card to the customer
To link the tokenized card information to the customer, your application will need to call the Create Card of Customer endpoint, which requires the id from the Create Customer endpoint in step 4.1 and the paymentTokenId from the Create Payment Token endpoint in step 4.2.
Sample request:
POST https://pg-sandbox.paymaya.com/payments/v1/customers/{id-from-create-customer-endpoint}/cards
{
"redirectUrl": {
"success": "https://www.merchantsite.com/success",
"failure": "https://www.merchantsite.com/failure",
"cancel": "https://www.merchantsite.com/cancel"
},
"paymentTokenId": "paymentTokenId-from-create-payment-token-endpoint"
}
The Create Card of Customer will return cardTokenId which you can use to process the customer's first payment and at the same time, the card information will also be saved for future use.
FAQ: What do I do with the
verificationUrlfield returned by Create Card of Customer?Answer: You may opt to ignore the
verificationUrlfromCreate Card of Customerendpoint if and only if you will use the first payment to verify the customer’s card to be saved.
4.4 Pay the transaction
To complete the customer’s first transaction and saving the card for future use, your application will need to call the Create Customer Payment endpoint and pass the (1) cardTokenId from the Create Card of Customer endpoint in step 4.3, (2) id from the Create Customer endpoint in step 4.1, and (3) required transaction details.
Sample request:
POST https://pg-sandbox.paymaya.com/payments/v1/customers/{id-from-create-customer}/cards/{cardTokenId-from-create-card-of-customer}/payments
{
"totalAmount": {
"amount": 100,
"currency": "PHP"
},
"redirectUrl": {
"success": "https://www.merchantsite.com/success",
"failure": "https://www.merchantsite.com/failure"
},
"requestReferenceNumber": "af094e84-d362-4f42-88b0-af72bfd62787"
}
The Create Customer Payment endpoint will return a verificationUrl. Your application must redirect the customer to this URL for 3DS authentication and payment completion.
4.5 [Optional] Retrieve Cards of Customer
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.
If your system needs to list down all the saved cards of a customer, you will need to call the Retrieve Cards of Customer endpoint.
Feeling lost?
Go to our demo website and see Maya Vault in action.
5 [Optional] Pay future transactions
Your application can use a verified cardToken on future transactions.
To pay future transactions, your application will need to call the Create Customer Payment endpoint and pass the (1) cardTokenId from the Create Card of Customer endpoint in step 4.3, (2) id from the Create Customer endpoint in step 4.1, and (3) required transaction details.
Sample request:
POST https://pg-sandbox.paymaya.com/payments/v1/customers/{id-from-create-customer}/cards/{cardTokenId-from-create-card-of-customer}/payments
{
"totalAmount": {
"amount": 100,
"currency": "PHP"
},
"redirectUrl": {
"success": "https://www.merchantsite.com/success",
"failure": "https://www.merchantsite.com/failure"
},
"requestReferenceNumber": "af094e84-d362-4f42-88b0-af72bfd62787"
}
FAQs
- Question: Will 3DS authentication be required when using a vaulted card?
Answer: No. It will only be asked during the first transaction of the customer.- Question: Can I build my own recurring scheduler for payments?
Answer: Yes, you can create your own scheduler and call Create Customer Payment according to your business rules.
6 Monitor real-time transaction events
Maya uses webhooks to notify your application when a specific event occurs with your payment request, such as when a customer decides not to authorize a payment, when a payment fails, or when a payment succeeds.
Learn more on how to create and configure your webhook →
7 Go Live Testing
For Online Payments, you will need to do the following test transactions in Sandbox or follow the email sent by the Maya Fulfillment Online Team.
- You will need to test the following card transactions in Maya Checkout: VISA, MasterCard and JCB.
You can use Maya’s list of mock test cards. - Ensure that your Webhooks are registered in Maya Manager. To validate, follow the instructions outlined in our Webhook guide →
Additional References
Updated over 1 year ago