Make on demand payments using a vaulted card
Tokenization and Vaulting
Step 1: Setup your Maya Business Manager Account
Before you could integrate Maya Card Payment Vault to your websites, you must register and setup your Maya Business Manager Account.
Step 2: Build your pages
Get the card details
Create a form that would accept the card details from the customer
Sample code:
<html>
<head>
<title>Save card</title>
</head>
<body>
<form action="/tokenize-customer-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">Link a card</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.
Get the Customer details
Create a form that would accept the required customer information when making card payments.
{
"id": "d29f1635-8313-4ed4-94e5-94b6a6018f52",
"firstName": "Maya",
"middleName": "Jose",
"lastName": "Juan",
"contact": {
"phone": "+63(2)1234567890",
"email": "[email protected]"
},
"billingAddress": {
"line1": "6F Launchpad",
"line2": "Sheridan Street",
"city": "Mandaluyong City",
"state": "Metro Manila",
"zipCode": "1552",
"countryCode": "PH"
},
"shippingAddress": {
"firstName": "Maya",
"middleName": "Jose",
"lastName": "Juan",
"line1": "6F Launchpad",
"line2": "Sheridan Street",
"city": "Mandaluyong City",
"state": "Metro Manila",
"zipCode": "1552",
"countryCode": "PH",
"phone": "+63(2)1234567890",
"email": "[email protected]",
"shippingType": "ST"
},
"sex": "F",
"birthday": "1987-07-28",
"customerSince": "2020-12-25",
"createdAt": "2021-07-06T14:01:25.000Z",
"updatedAt": "2021-07-06T14:01:25.000Z"
}
Step 3: Submit details for tokenization
Tokenize the card details
Once customer have provided their card details, your system must send these information to /payments/v1/payment-tokens
endpoint and obtain the paymentTokenId
.
Sample code:
const createPaymentTokenUrl = 'https://pg-sandbox.paymaya.com/payments/v1/payment-tokens';
const options = {
headers: {
'Content-Type': 'application/json',
'Authorization': `Basic ${btoa('SECRET_KEY')}`
},
method: 'POST',
body: cardData
};
const paymentTokenId = await fetch(createPaymentTokenUrl, options)
.then(res => res.json())
.then(json => {
return json.paymentTokenId
})
.catch(err => console.error('error:' + err));
Submit customer details
Submit the customer details to Maya vault and obtain the unique customer ID via the /payments/v1/customers
endpoint.
Maya recommends that you keep the
Id
of the customer record from the response. ThisId
can be used to retrieve customer details and card tokens.
Sample code:
const createCustomerUrl = 'https://pg-sandbox.paymaya.com/payments/v1/customers';
const options = {
headers: {
'Content-Type': 'application/json',
'Authorization': `Basic ${btoa('SECRET_KEY')}`
},
method: 'POST',
body: customerData
};
const customerIdFromMayaVault = await fetch(createCustomerUrl, options)
.then(res => res.json())
.then(json => {
// Your code to keep the customerId on your application
return json.id
})
.catch(err => console.error('error:' + err));
Step 4: Link paymentTokenId
to the customer
At this point, you will have two (2) variables available - customerId
and paymentTokenId
. Send these variables to /payments/v1/customers/{customerIdFromMayaVault}/cards
endpoint to link them together.
paymentTokenId can only be linked once. Attempts after successful link will reject the request.
Sample code:
const createCustomerCardUrl = 'https://pg-sandbox.paymaya.com/payments/v1/customers/${customerIdFromMayaVault}/cards';
const options = {
headers: {
'Content-Type': 'application/json',
'Authorization': `Basic ${btoa('SECRET_KEY')}`
},
method: 'POST',
body: {
paymentTokenId,
redirectUrl: {
success: 'http://localhost:8080/success',
failure: 'http://localhost:8080/failure',
cancel: 'http://localhost:8080/cancel',
}
}
};
fetch(createCustomerCardUrl, options)
.then(res => res.json())
.then(cards => {
// Assuming first entry in cards list has VERIFIED state
const cardTokenId = cards[0].cardTokenId
response.redirect(303, json.verificationUrl)
})
.catch(err => console.error('error:' + err));
You can also save the
cardTokenId
for future use, but be aware that a customer can have multiple cards and may have set their default cards. To retrieve and validate the customer’s cards, call the GET /payments/v1/customers/{customerId}/cards endpoint.
You will notice that linking of customer to their credit card will return 2 items: cardTokenId
and verificationUrl
. Your application should redirect to the verificationUrl
in order to trigger user authentication which will depend on the issuing bank's 3DS authentication.
Verification
There are 2 flows to verifying the linked card: through test charge of Php 10.00 or through payment of their current transaction.
- Through Test Charge
- Through payment of current transaction
From the successful call of the POST
, your application should be redirected to the verificationUrl
from the response data to continue the verification process.
We will be charging Php 10 to the customer's card. This amount will be automatically refunded back.
Initiate the payment of the current customer transaction through POST
. This will give you a new verificationUrl
that your application should redirect to.
Quick Test
- Input card details using one of our test cards.
- Click the Link a card button.
- You are redirected to Issuing Bank's verification page.
- On successful verification, your customer will be redirected to the success page.
Retrieve Cards of the Customer
Use this endpoint to retrieve and validate the cards of a customer.
These fields would help you identify which is the default usable card of the customer:
state (string) | Indicates the state of the card being attached to the customer:PREVERIFICATION : 3DS verification is required to add the card to the customer.VERIFIED : card is successfully added to the customer.EXPIRED : an attempt to add the card to the customer has expired. |
default | Indicates if the card is the default card of the customer. |
If you are looking for the default usable card, you must get the cardTokenId with state =
VERIFIED
and default =true
.
Making Payments
Step 1: Execute on-demand payments
Use the acquired cardToken and customer ID from Maya Vault to execute payments anytime.
For this integration, Maya Card Payment Vault serves as a secure card storage only. Scheduling and triggering of payments will be done by your system.
Sample code:
async app.post('/customers/:customerId/cards/:cardToken/execute-payment-from-customer-card', async (request, response) => {
const url = `https://pg-sandbox.paymaya.com/payments/v1/customers/{request.params.customerId}/cards/{request.params.cardToken}/payments`;
const options = {
method: 'POST',
headers: {accept: 'application/json', 'content-type': 'application/json'},
body: request.body
};
const response = await fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error('error:' + err));
})
Step 2: Handle post-payment events
The redirection after a successful payment does not guarantee that the payment information will be updated. Your application should manage payment information updates by implementing webhooks.
Useful Links
Updated 10 months ago