PayMaya Checkout FAQ
Posted by Diwa del Mundo, John Lawrence Poklay, Dan Leland Suarez, Ken Sia • Tuesday August 08, 2017 09:32 AM

General

Keys and Authentication

3-D Secure

Webhooks

Checkout

Security

 

General

 

Q: What can I do with PayMaya Checkout?

PayMaya Checkout allows you to:

 

  • Accept credit and debit card payments from customers
  • Provide customers’ with an enhanced online shopping experience
  • Obtain information on payments fulfilled using the PayMaya Checkout page
  • Receive real-time transaction notifications through the use of webhooks

 

Q: What payment schemes are supported by PayMaya?

PayMaya Checkout currently supports payments made using Visa and MasterCard credit/debit cards.

 

Q: What currencies are supported by the solution?

PayMaya Checkout accepts transactions made in Philippine Pesos (PHP).

 

Q: Can I customize my PayMaya checkout page?

Yes! This feature is one of the many benefits PayMaya offers its Checkout API clients. PayMaya Checkout supports:

 

  • Brand or logo customization
  • Color scheme customization

 

Q: How can I get started?

Ready to begin receiving online payments? Integrate your web or mobile application with the Checkout API sandbox environment.

 

Q: Does the Checkout API feature usage limits?

As of May 2016, the Checkout API supports unlimited usage.

 

Keys and Authorization

 

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

For testing and evaluation purposes, you can visit this page to get test API keys and test credit card numbers.

 

Access to production API keys for accepting payments require you to apply as a PayMaya Business merchant. Visit the PayMaya Business web site for the documentary requirements.

 

Q: I already have an API key. How do I use it to send requests to Checkout API?

To send requests to Checkout API, perform basic authorization using your API key and then use this key in the Authorization header.

 

Note: All requests sent to PayMaya Checkout API must contain an Authorization header.

 

Q: How do I perform basic authorization?

Basic authorization requires the use of a Username and Password. The Username is your API key and your default Password is blank.

 

Steps:

 

1. Indicate your Username and Password separated by a colon (:).

 

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

pk-8rOz4MQKRxd5OLKBPcR6FIUx4Kay71kB3UrBFDaH172:

 

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

 

cGstaWFpb0JDMnBiWTZkM0JWUlNlYnNKeGdoU0hlSkRXNG42bmF2STd0WWRyTjo=

 

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

Authorization: Basic cGstaWFpb0JDMnBiWTZkM0JWUlNlYnNKeGdoU0hlSkRXNG42bmF2STd0WWRyTjo=

 

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

When you sign up to PayMaya Checkout, you are provided with two keys: a public-facing key and a secret key. For API endpoints accessed over a public environment, such as web and mobile applications, authentication is performed using the public-facing key. For confidential endpoints, such as checkout status retrieval and webhook registration, authentication is done using the secret key.

 

Q: Why are there two API keys?

Two API keys are used by PayMaya Checkout because certain Checkout API endpoints are designed for access over a public environment, such as the Internet, and some API endpoints, such as webhook registration, are confidential.

 

Initiate checkout of items

POST https://sandbox-checkout-api.paymaya.com/v1/checkouts

Authorization: Basic < Base64-encoded Public-facing Key >

 

Register a webhook

POST https://sandbox-checkout-api.paymaya.com/v1/webhooks

Authorization: Basic < Base64-encoded Secret Key >

 

Q: What if other parties receive my public-facing and secret API keys?

Let’s face it: sometimes, accidents happen. The public-facing key is meant to be used in non-confidential environments or Internet-facing web and mobile applications. This means losing your public-facing key poses no danger to your business. If your secret key is lost, however, contact PayMaya as soon as you can. We will immediately disable this key and provision a new one for you.

 

3-D Secure

 

Q: What is 3-D Secure?

3-Domain (3-D) Secure is an XML-based protocol used to authenticate cardholders when performing transactions over the Internet.

 

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

3-D Secure authentication is performed before payment processing. If the card entered by a customer is enrolled in a payment authentication scheme, PayMaya Checkout directs him/her to the card issuer’s authentication page. If the cardholder fails 3-D Secure authentication, payment is stopped and the paymentStatus field of the checkout returns an AUTH_FAILURE value.

 

Webhooks

 

Q: What are Webhooks?

A webhook, also called a web callback, is an application that notifies you of Checkout API events, such as successful payment processing. This notification is sent to your application URL.

 

Q: How can I use the Webhook feature in Checkout API?

The Checkout API classifies events as either CHECKOUT_SUCCESS or  CHECKOUT_FAILURE. If you wish to receive information regarding successful or failed payments, you can register URLs to receive this information.

 

For successful payments, the PayMaya Checkout server performs an HTTP POST operation to the URL you registered for the CHECKOUT_SUCCESS webhook. Failed payments are posted to the CHECKOUT_FAILURE webhook.

 

Checkout

 

Q: How can I track the status of a checkout?

You can retrieve your checkout information endpoint or use webhooks to track the status of a checkout. Each checkout will include checkoutStatus and paymentStatus fields, indicating the overall status of the checkout and the status of the payment transaction, respectively.

 

Q: What are the different checkout and payment statuses available?

The checkoutStatus field is populated with one of the following values:

STATUS DESCRIPTION
CREATED Default value when a checkout is created
EXPIRED Checkout reached expiration
PROCESSING When the customed accessed the checkout URL
COMPLETED Last state of checkout; paymentStatus can be AUTH_FAILURE, PAYMENT_SUCCESS or PAYMENT_FAILURE

The paymentStatus field can be PENDING, AUTH_SUCCESS, AUTH_FAILURE, PAYMENT_SUCCESS, or  PAYMENT_FAILURE.

PAYMENT STATUS DESCRIPTION
PENDING Default value of paymentStatus field
AUTH_SUCCESS When the cardholder passed the 3DS authentication
AUTH_FAILURE When the cardholder failed the 3DS authentication. This triggers the checkout state to be set to COMPLETED
PAYMENT_SUCCESS Payment was processed successfully
PAYMENT_FAILURE Payment processing failed

 

Q: How quickly does a checkout expire?

All checkouts expire in one (1) hour.

 

Security

 

Q: Should I be concerned with PCI-DSS Compliance?

Payment Card Industry Data Security Standards (PCI-DSS) apply to any business that stores, processes, or transmits payment cardholder data, including credit card number, expiry date, and security code. Since PayMaya manages and secures your customers’ payment cardholder data, your PCI-DSS scope is drastically reduced. This feature, however, does not exempt you from complying with PCI-DSS Self-Assessment Questionnaire (SAQ) requirements. The SAQ is a validation tool that helps merchants evaluate their PCI-DSS compliance.

 

The SAQ type most appropriate to your business is SAQ A, which is defined by PCI-DSS as:

 

"Card-not-present merchants (e-commerce or mail/telephone-order) that have fully outsourced all cardholder data functions to PCI DSS compliant third-party service providers, with no electronic storage, processing, or transmission of any cardholder data on the merchant’s systems or premises.

 

Not applicable to face-to-face channels."

 

More information on the SAQ can be found in the PCI-DSS SAQ Overview Document and the Self-Assessment Questionnaire A and Attestation of Compliance Document.

 

Q: Can other merchants or parties view my transactions?

Only you can view/retrieve information regarding your own checkout pages.