Payment Vault FAQ
Posted by Diwa del Mundo, John Lawrence Poklay, Abby Alcantara • Tuesday February 06, 2018 04:53 AM


Keys and Authentication

3-D Secure







Q: What can I do with PayMaya Payment Vault?

  • Accept payments using credit card and debit card payments from customers
  • Enhance and secure payments
  • Receive real-time transaction notification through the use of Webhooks
  • Vault customer and card information
  • Charge a customer's card for subscription payments
  • Perform void and refund of payments


Q: What are the supported payment schemes?

PayMaya Payment Vault currently supports Visa and MasterCard credit / debit cards.


Q: How can I get started?

You need to integrate first with the Payment Vault sandbox environment. Paymaya Payment Vault offers a lot of services such as one-time tokenized payments, card vaulting (on-demand payments), subscriptions, etc. You can use the test cards and API keys during integration but it is advisable to use your own Sandbox API keys which  you can request from us. 


Q: Are there any API usage limits?

As of today, there are no limits.


Keys and Authorization


Q: How can I get keys to access the API?

You can use the Payment Vault document. It has the API console that was pre-configured with the Sandbox API keys. You can perform payment transactions using the API console.


You can also get the keys in the Merchant Document.


For your own sandbox and production, contact us for your production API key.


Q: I already have an API key. How will I use it to send requests to Payment Vault?

You have to perform a basic authorization using your API key then use it as the value of the Authorization header. This way, we will be able to determine if the request is coming from a valid merchant that has valid access to Payment Vault.

Note: Every request sent to PayMaya Payment Vault must contain an Authorization header.


Q: How do I perform Basic Authorization?

Basic Authorization consists of a Username and Password. The Username is your API key and you have to set Password as blank.


Step 1: Combine Username and Password separated by ‘:’ (colon).

If your API key is "pk-iaioBC2pbY6d3BVRSebsJxghSHeJDW4n6navI7tYdrN", the resulting string is:



Step 2: Apply Base64 encoding to the resulting string from Step 1.

Using the resulting string from Step 1, the Base64 encoded string will be:



Step 3: Indicate the authorization method i.e. “Basic” followed by a space then the Base64 encoded string in Step 2. 


Authorization: Basic cGstaWFpb0JDMnBiWTZkM0JWUlNlYnNKeGdoU0hlSkRXNG42bmF2STd0WWRyTjo=


Q: What are public-facing and secret API keys?

You will be given a key set composed of 2 keys: a public-facing key and a secret key. For API endpoints designed to be accessed on a public environment like web and mobile applications, authentication is done through the public-facing key. The generation of Payment Token is configured to use the public-facing key. For confidential endpoints, like payment, card vault, void, refund, and webhook registration, authentication is done using your secret key.

Q: Why are there two (2) kinds of API keys?

Payment Vault has endpoints configured to be accessible over the internet and some are configured to be on a secured network connection.

See this Merchant Document for the sample keys available in sandbox.

Q: What if other parties get hold of my public-facing and secret API keys?

For your public-facing key, you do not need to worry! The public-facing key is expected to be used on non-confidential environments or internet-facing web and mobile applications. On the other hand, your secret key needs to be safely protected. Make sure that only confidential and privileged systems like your web and API application backends have access to it. In case your secret key is accessed by an unauthorized user, please contact us and we will disable your secret key and provision a new one for you.


3-D Secure


Q: What is 3-D Secure?

3-D Secure or 3-Domain Secure is a protocol that is used to authenticate cardholders when performing transactions over the Internet. 


Q: How is payment authentication done through the PayMaya Checkout page?

3-D Secure authentication is performed before payment processing. If the card entered is enrolled in a payment authentication scheme, PayMaya Checkout will authenticate the cardholder by redirecting them to their card issuer where they previously registered a password (some card issuers sends an OTP - One-Time PIN). If the cardholder fails the 3-D Secure authentication, payment will not proceed. The paymentStatus field of the checkout will be set to AUTH_FAILURE.



Q: What are Webhooks?
A Webhook, also called a web callback, is a way to notify your application for Payment Vault events such as successful payment processing. The notification will be sent to your registered application URL.

Q: How can I use the Webhook feature in Payment Vault?
The 3-D secure payment utilizes the webhook feature. It classifies events such as successful payments with 3-D S and subscription payments.

For successful payments, the Paymaya Payment server will do a HTTP POST the the url you registered for 3DS_PAYMENT_SUCCESS. For failed payments, it will be forwarded to the url registered for 3DS_PAYMENT_FAILURE. For subscription payment results, Paymaya Payment Vault will call urls registered for  RECURRING_PAYMENT_SUCCESS or RECURRING_PAYMENT_FAILURE.




Q: What are the different payment statuses available?

There are different statuses for each services in Paymaya Payment Vault. It is available in the Payment Document.

Q: How long until a payment token is considered expired?

Each payment token has an expiry of 15 minutes.

Card tokens need to be verified within 15 minutes. Once verified, card tokens can be used for payments any time.


Q: Can other Merchants or Parties view my transactions?

Only you, the Merchant, who performed the payment can view/retrieve the information about that payment.

Q: When should I void a transaction and how does it work?

Void transaction allows you to cancel the payment made before it has been settled. You can void a transaction, using the payment ID, before the 6PM cut-off period of the same day.

Q: When should I refund a transaction and how does it work ?

Refund transaction allows you to refund the payment even after the amount has been settled. You can refund the transaction, using the payment ID, if it is no longer eligible for void with the option of partial or full refund of the payment.


Q: How much can be refunded from a transaction?

You can refund the full amount of the transaction.

Q: Can I do multiple refunds for a single transaction?

Yes. You can do partial refunds for a transaction as long as their total amount does not exceed the amount paid for the transaction.

Q: Is there a limit on how many transactions I can refund/void for a day?

For refund, there is no limit as to how many refund transaction you can perform in a day.

For void, there is a cut-off period of 6pm of the same day of the payment in which you can void the transaction.

Q: Can I refund/void payments from all Paymaya Payment Vault services?

Yes, you can refund /void all payments made through Payment Vault.

Q: Is there any additional charge/fee for voiding/refunding a transaction?

There are no additional charge when you void/refund a transaction.



Q: Should I be concerned with PCI DSS Compliance?

The Payment Card Industry Data Security Standards (PCI DSS) applies to any business that stores, processes, or transmits payment cardholder data (credit card number, expiry date, and security code). Since PayMaya manages and secures your customer's payment cardholder data, your PCI-DSS scope has been drastically reduced. It does not, however, exempt you from complying to the PCI-DSS Self-Assessment Questionnaires (SAQs) requirements. These SAQs are validation tools that will assist in self-evaluation of PCI-DSS compliance.


There are different types of SAQs, e.g. A, A-EP, C, etc. The most appropriate type in your case would be SAQ A-EP defined by PCI DSS as:


"SAQ A-EP merchants are e-commerce merchants who partially outsource their e-commerce payment channel to PCI DSS validated third parties and do not electronically store, process, or transmit any cardholder data on their systems or premises. "


For more information, please see the PCI-DSS SAQ Overview Document and the Self-Assessment Questionaire A-EP and Attestation of Compliance Document.