# PayMaya Payment Gateway - Invoice
## API Authentication
Authentication is done via HTTP Basic Authentication. Depending on the API, the public / secret key must be provided as the username and the password left as blank.
Steps are as follows:
1. Combine Username and Password (left blank) separated by ‘:’ (colon). If your API key is “pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah”, the resulting string is:
```no-highlight
pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah:
```
2. Apply Base64 encoding to the resulting string from Step 1. Using the resulting string from Step 1, the Base64 encoded string will be:
```no-highlight
cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
```
3. Indicate the authorization method i.e. “Basic” followed by a space then the Base64 encoded string in Step 2. An example is shown below.
```no-highlight
Authorization: Basic cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
```
(see [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication))
## Environment Setup
PayMaya Payment Gateway has two environments:
**Sandbox** and **Production**.
**Sandbox** is used for development, testing and integration. Once integration is completed on this environment it will be verified by our Merchant Services team. Only then will production credentials be provided.
##### Sandbox Url: https://pg-sandbox.paymaya.com
> Load testing is not allowed on both environments. If you have need for load testing please contact us.
**Production** is for live payments. Testing in this environment will incur real charges
##### Sandbox Url: https://pg.paymaya.com
## Sandbox Test Credentials
| MERCHANT NAME | SECRET API KEY | PUBLIC API KEY SERVICE
|-|-|-
| Sandbox Party 1 | sk-X8qolYjy62kIzEbr0QRK1h4b4KDVHaNcwMYk39jInSl | pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah |
| Sandbox Party 2 | sk-KfmfLJXFdV5t1inYN8lIOwSrueC1G27SCAklBqYCdrU | pk-eo4sL393CWU5KmveJUaW8V730TTei2zY8zE4dHJDxkF |
| Sandbox Party 3 | sk-fzukI3GXrzNIUyvXY3n16cji8VTJITfzylz5o5QzZMC | pk-lNAUk1jk7VPnf7koOT1uoGJoZJjmAxrbjpj6urB8EIA |
| Sandbox Party 4 | sk-VGDKY3P90NYZZ0kSWqBFaD1NTIXQCxtdS7SbQXvcA4g | pk-yaj6GVzYkce52R193RIWpuRR5tTZKqzBWsUeCkP9EAf |
| Sandbox Party 5 | sk-8MqXdZYWV9UJB92Mc0i149CtzTWT7BYBQeiarM27iAi | pk-NCLk7JeDbX1m22ZRMDYO9bEPowNWT5J4aNIKIbcTy2a |
> These sandbox credentials are for public use, and other users might be using them simultaneously.
> Once you are onboarded with PayMaya you will be granted private access credentials, first in sandbox, then in production.
## Sandbox Test Cards
| CARD TYPE | NUMBER | EXPIRY MONTH | EXPIRY YEAR | CSC/CVV | 3-D Secure PASSWORD
|-|-|-|-|-|-
| MASTERCARD | 5123456789012346 | 12 | 2025 | 111 | Not enabled
| MASTERCARD | 5453010000064154 | 12 | 2025 | 111 | secbarry1
| VISA | 4123450131001381 | 12 | 2025 | 123 | mctest1
| VISA | 4123450131001522 | 12 | 2025 | 123 | mctest1
| VISA | 4123450131004443 | 12 | 2025 | 123 | mctest1
| VISA | 4123450131000508 | 12 | 2025 | 111 | Not enabled
> These test cards are for Sandbox use only! They will not work on Production. Live cards will also not work on Sandbox
> For a full list of cards and additional test cases please refer [here](https://mock-processor-sandbox.paymaya.com/cards)
## Invoice
* Invoices are a recording of a payment transaction between Merchant and Customer. Invoices can keep track of multiple payments.
* Invoices do not expire, they are ideal for requesting payment over a long period of time. If requesting for immediate payment, you may want to use [PayMaya Checkout](https://hackmd.io/@paymaya-pg/Checkout) instead.
### Payment Flow
```mermaid
sequenceDiagram
Merchant ->> Payment Gateway: Create Invoice
Payment Gateway -->> Merchant: Return invoiceUrl
Merchant -->> Customer: Send invoiceUrl
Customer ->> Payment Gateway: Customer completes checkout
Payment Gateway -->> Customer: Show status page
alt Payment Confirmation
Customer ->> Merchant: Redirect back to Merchant
Merchant ->> Payment Gateway: Get Payment
Payment Gateway -->> Merchant: Returns
else
Payment Gateway ->> Merchant: Sends Webhook
end
```
### Types and Statuses
* Invoice Types
`SINGLE` - Once a payment is completed the invoice will no longer be usable
`OPEN` - Can accept multiple payments continuously. May not have a totalAmount.amount.
* Invoice Statuses
`PENDING` - Invoice can accept payments
`COMPLETED` - Invoice can no longer accept payments
`CANCELLED` - Invoice did not and will not accept payments
* Invoice payments are accepted via [PayMaya Checkout](https://hackmd.io/@paymaya-pg/Checkout). Checkout API for is applicable for returned payment records.
* ! Invoice API is not compatible with PayMaya Manager invoicing at this time.
### Invoice API
#### Create `SINGLE` Invoice - POST https://pg-sandbox.paymaya.com/invoice/v2/invoices
> Requires secret key
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
##### Body
```
{
"invoiceNumber": "INV0001",
"type": "SINGLE",
"totalAmount": {
"value": 100,
"currency": "PHP"
},
"redirectUrl": {
"success": "https://www.merchantsite.com/success",
"failure": "https://www.merchantsite.com/failure",
"cancel": "https://www.merchantsite.com/cancel"
},
"requestReferenceNumber": "1551191039",
"metadata": {}
}
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"invoiceId": "1b5cfd3e-130a-459d-94d5-33ca3fba4a10",
"invoiceUrl": "https://payments-web-sandbox.paymaya.com/invoice?id=1b5cfd3e-130a-459d-94d5-33ca3fba4a10"
}
```
#### Create `OPEN` Fixed Amount Invoice - POST https://pg-sandbox.paymaya.com/invoice/v2/invoices
> Requires secret key
> `OPEN` Invoices without amount will request customer to input payment amount.
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
##### Body
```
{
"invoiceNumber": "INV0001",
"type": "OPEN",
"totalAmount": {
"value": 100,
"currency": "PHP"
},
"redirectUrl": {
"success": "https://www.merchantsite.com/success",
"failure": "https://www.merchantsite.com/failure",
"cancel": "https://www.merchantsite.com/cancel"
},
"requestReferenceNumber": "1551191039",
"metadata": {}
}
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"invoiceId": "1b5cfd3e-130a-459d-94d5-33ca3fba4a10",
"invoiceUrl": "https://payments-web-sandbox.paymaya.com/invoice?id=1b5cfd3e-130a-459d-94d5-33ca3fba4a10"
}
```
#### Create `OPEN` Variable Amount Invoice - POST https://pg-sandbox.paymaya.com/invoice/v2/invoices
> Requires secret key
> `OPEN` Invoices without amount will request customer to input payment amount.
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
##### Body
```
{
"invoiceNumber": "INV0001",
"type": "OPEN",
"totalAmount": {
"currency": "PHP"
},
"redirectUrl": {
"success": "https://www.merchantsite.com/success",
"failure": "https://www.merchantsite.com/failure",
"cancel": "https://www.merchantsite.com/cancel"
},
"requestReferenceNumber": "1551191039",
"metadata": {}
}
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"invoiceId": "1b5cfd3e-130a-459d-94d5-33ca3fba4a10",
"invoiceUrl": "https://payments-web-sandbox.paymaya.com/invoice?id=1b5cfd3e-130a-459d-94d5-33ca3fba4a10"
}
```
#### Get Invoice - GET https://pg-sandbox.paymaya.com/invoice/v2/invoices/:invoiceId
Retrieves an Invoice.
> Requires secret key
> Invoices are not updated in real time. Delay is a maximum of 5 minutes.
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"id": "1b5cfd3e-130a-459d-94d5-33ca3fba4a10",
"invoiceNumber": "INV0001",
"type": "SINGLE",
"totalAmount": {
"value": "100.00",
"currency": "PHP",
"details": null
},
"items": [],
"requestReferenceNumber": "1551191039",
"merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
"createdAt": "2020-09-23T08:00:53.498Z",
"updatedAt": "2020-09-23T08:10:34.257Z",
"completedAt": "2020-09-23T08:10:34.256Z",
"status": "COMPLETED",
"redirectUrl": {
"success": "https://www.merchantsite.com/success",
"failure": "https://www.merchantsite.com/failure",
"cancel": "https://www.merchantsite.com/cancel"
},
"metadata": {},
"authorizationType": null,
"payments": [
{
"checkoutId": "e21e35a7-f865-4a1c-9f79-a41638ffe3d8",
"createdAt": "2020-09-23T08:05:17.000Z",
"updatedAt": "2020-09-23T08:10:34.251Z",
"paymentAt": "2020-09-23T08:05:35.000Z",
"status": "SUCCESS"
}
]
}
```
#### Get Invoices - GET https://pg-sandbox.paymaya.com/invoice/v2/invoices
Retrieve a list of Invoices.
> Requires secret key
> Invoices are not updated in real time. Delay is a maximum of 5 minutes.
**Request**
The following **optional** get parameters are accepted:
|Parameter|Description| Validation
|-|-|-
|invoiceNumber| Filter by invoice number exact match | Valid alphanumeric
|requestReferenceNumber| Filter by request reference number exact match | Valid alphanumeric
|type| Filter by type exact match | Valid type ['SINGLE', 'OPEN']
|status|Filter by status exact match| Valid status ['PENDING', 'COMPLETED', 'CANCELLED']
|limit|Number of invoices to be returned| 1-50
|skip|Number of invoice records to be skipped| numeric
|order|Sorting | string _(see details below on syntax)_
_Order syntax:_
* Field names separated by a comma. Prepend with a minus (`-`) for descending order. No prepended symbol is ascending order.
```
field1[,field2,field3,...]
```
* Sort by type
```
type
```
* Sort by status (asc), createdAt (desc)
```
status,-createdAt
```
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"totalCount": 3,
"pageCount": 3,
"invoices": [
{
"id": "53d77f1a-c867-487d-a6f8-fcd86030d59c",
"invoiceNumber": "INV0001",
"type": "SINGLE",
"totalAmount": {
"value": "100.00",
"currency": "PHP",
"details": null
},
"items": [],
"requestReferenceNumber": "1551191039",
"merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
"createdAt": "2020-09-23T08:13:45.397Z",
"updatedAt": "2020-09-23T08:13:45.397Z",
"completedAt": null,
"status": "PENDING",
"redirectUrl": {
"success": "https://www.merchantsite.com/success",
"failure": "https://www.merchantsite.com/failure",
"cancel": "https://www.merchantsite.com/cancel"
},
"metadata": {},
"authorizationType": null
},
{
"id": "1b5cfd3e-130a-459d-94d5-33ca3fba4a10",
"invoiceNumber": "INV0001",
"type": "SINGLE",
"totalAmount": {
"value": "100.00",
"currency": "PHP",
"details": null
},
"items": [],
"requestReferenceNumber": "1551191039",
"merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
"createdAt": "2020-09-23T08:00:53.498Z",
"updatedAt": "2020-09-23T08:10:34.257Z",
"completedAt": "2020-09-23T08:10:34.256Z",
"status": "COMPLETED",
"redirectUrl": {
"success": "https://www.merchantsite.com/success",
"failure": "https://www.merchantsite.com/failure",
"cancel": "https://www.merchantsite.com/cancel"
},
"metadata": {},
"authorizationType": null
},
{
"id": "286f3e86-12ea-4a66-966e-56e81b667136",
"invoiceNumber": "INVOICE00002",
"type": "OPEN",
"totalAmount": {
"value": null,
"currency": "PHP",
"details": null
},
"items": [],
"requestReferenceNumber": "PGQEINVOICE",
"merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
"createdAt": "2020-09-23T07:00:32.380Z",
"updatedAt": "2020-09-23T07:00:32.380Z",
"completedAt": null,
"status": "PENDING",
"redirectUrl": null,
"metadata": {},
"authorizationType": null
}
]
}
```
#### Cancel Invoice - DELETE https://pg-sandbox.paymaya.com/invoice/v2/invoices/:invoiceId
> Requires secret key
> If Invoice type is `SINGLE` and status is `PENDING`, status will be set to `CANCELLED`
> If Invoice type is `OPEN` and has NO Payments, status will be set to `CANCELLED`
> If Invoice type is `OPEN` and has Payments, status will be set to `COMPLETED`
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"id": "53d77f1a-c867-487d-a6f8-fcd86030d59c",
"invoiceNumber": "INV0001",
"type": "SINGLE",
"totalAmount": {
"value": "100.00",
"currency": "PHP",
"details": null
},
"items": [],
"requestReferenceNumber": "1551191039",
"merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
"createdAt": "2020-09-23T08:13:45.397Z",
"updatedAt": "2020-09-23T08:21:35.612Z",
"completedAt": null,
"status": "CANCELLED",
"redirectUrl": {
"success": "https://www.merchantsite.com/success",
"failure": "https://www.merchantsite.com/failure",
"cancel": "https://www.merchantsite.com/cancel"
},
"metadata": {},
"authorizationType": null,
"payments": []
}
```
## PayMaya Me Link
* PayMaya Me Link wraps the Invoice in a personalized URL.
* Ideal for use with `OPEN` Variable Amount Invoices. The link can be sent to multiple customers.
* Try it now! https://sandbox.paymaya.me/sample
### PayMaya Me Flow
```mermaid
sequenceDiagram
Merchant ->> Payment Gateway: Create Invoice
Payment Gateway -->> Merchant: Return invoiceUrl
Merchant ->> Payment Gateway: Check PayMayaMeUrl availability
Payment Gateway -->> Merchant: Return availability
Merchant ->> Payment Gateway: Register Invoice PayMayaMeUrl
Payment Gateway -->> Merchant: Return PayMayaMeUrl
loop Accept multiple payments
Merchant -->> Customer: Send PayMayaMeUrl
Customer ->> Payment Gateway: Customer completes checkout
Payment Gateway -->> Customer: Show status page
alt Payment Confirmation
Customer ->> Merchant: Redirect back to Merchant
Merchant ->> Payment Gateway: Get Payment
Payment Gateway -->> Merchant: Returns
else
Payment Gateway ->> Merchant: Sends Webhook
end
end
```
### PayMaya Me API
#### Check PayMayaMeUrl Name - GET https://pg-sandbox.paymaya.com/invoice/v2/custom-urls/check?name=:name
Checks if PayMaya Me Url path is available
> Requires secret key
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"isAvailable": true
}
```
#### Register PayMayaMeUrl - POST https://pg-sandbox.paymaya.com/invoice/v2/custom-urls
Registers an invoice to a PayMaya Me Url path
> Requires secret key
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
##### Body
```
{
"invoiceId": "73759488-a84e-481d-97e2-cc67b528b326",
"name": "devportal"
}
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"invoiceId": "efa2b1bc-5e3f-4c13-a2ab-a3511fa4a9c8",
"name": "devportal",
"customUrl": "https://sandbox.paymaya.me/devportal",
"originalUrl": "https://payments-web-sandbox.paymaya.com/invoice?id=efa2b1bc-5e3f-4c13-a2ab-a3511fa4a9c8"
}
```
#### GET PayMayaMeUrl of Invoice - GET https://pg-sandbox.paymaya.com/invoice/v2/invoices/:invoiceId/custom-url
Checks the PayMaya Me Url path registered an invoice
> Requires secret key
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"invoiceId": "efa2b1bc-5e3f-4c13-a2ab-a3511fa4a9c8",
"name": "devportal",
"customUrl": "https://sandbox.paymaya.me/devportal",
"originalUrl": "https://payments-web-sandbox.paymaya.com/invoice?id=efa2b1bc-5e3f-4c13-a2ab-a3511fa4a9c8"
}
```
#### Deregister PayMayaMeUrl - DELETE https://pg-sandbox.paymaya.com/invoice/v2/custom-urls
Deregisters a PayMaya Me Url path
> Requires secret key
> Please do not deregister the sample!
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
##### Body
```
{
"invoiceId": "013241bb-ed77-4ce4-b254-d946c7b318be",
"name": "sample"
}
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"result": "OK"
}
```
## Other API
* Invoice payments are accepted via [PayMaya Checkout](https://hackmd.io/@paymaya-pg/Checkout). Checkout API for is applicable for returned payment records. The Checkout Id is returned on the GET Invoice API.
### Checkout API
#### Get Checkout - GET https://pg-sandbox.paymaya.com/checkout/v1/checkouts/:checkoutId
Retrieves a Payment.
> Requires secret key
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"id": "73759488-a84e-481d-97e2-cc67b528b326",
"items": [
{
"name": "Canvas Slip Ons",
"quantity": 1,
"code": "CVG-096732",
"description": "Shoes",
"amount": {
"value": 100,
"details": {
"discount": 0,
"serviceCharge": 0,
"shippingFee": 0,
"tax": 0,
"subtotal": 100
}
},
"totalAmount": {
"value": 100,
"details": {
"discount": 0,
"serviceCharge": 0,
"shippingFee": 0,
"tax": 0,
"subtotal": 100
}
}
}
],
"requestReferenceNumber": "1551191039",
"createdAt": "2019-02-26T14:23:57.000Z",
"updatedAt": "2019-02-26T14:25:51.000Z",
"expiredAt": "2019-02-26T14:40:47.000Z",
"paymentScheme": "master-card",
"expressCheckout": true,
"refundedAmount": 0,
"canPayPal": false,
"status": "COMPLETED",
"paymentStatus": "PAYMENT_SUCCESS",
"paymentDetails": {
"responses": {
"data": {
"efs": {
"financialNetworkCode": "MCC",
"acquirerResponseCode": "00",
"transactionNumber": "1100000067",
"cardType": "MC",
"transactionIdentifier": "0110SL",
"marketSpecificData": "null",
"commercialCardIndicator": "1",
"cardLevelIndicator": "null",
"maskedResponseMetadatadCardNumber": "null",
"riskCategory": "LOW",
"returnACI": "null",
"authorizeId": "006170",
"riskScore": 0.75,
"commercialCard": "N",
"batchNumber": "20170206",
"receipt_number": "703717440845"
}
},
"links": [
{
"rel": "self"
}
],
"metadata": {
"transaction_reference_no": "316fb46d-5d55-465e-8f42-9fff2aaa6fa9"
}
},
"paymentAt": "2019-02-26T14:25:51.000Z",
"3ds": true
},
"buyer": {
"firstName": "John",
"middleName": "Paul",
"lastName": "Doe",
"contact": {
"phone": "+639181008888",
"email": "merchant@merchantsite.com"
},
"billingAddress": {
"line1": "6F Launchpad",
"line2": "Reliance Street",
"city": "Mandaluyong City",
"state": "Metro Manila",
"zipCode": "1552",
"countryCode": "PH"
},
"shippingAddress": {
"line1": "6F Launchpad",
"line2": "Reliance Street",
"city": "Mandaluyong City",
"state": "Metro Manila",
"zipCode": "1552",
"countryCode": "PH"
},
"ipAddress": "125.60.148.241",
"birthday": "1995-10-24",
"sex": "M"
},
"merchant": {
"currency": "PHP",
"email": "paymentgatewayteam@paymaya.com",
"locale": "en",
"homepageUrl": "http://www.paymaya.com",
"isEmailToMerchantEnabled": "false",
"isEmailToBuyerEnabled": "false",
"isPaymentFacilitator": "false",
"isPageCustomized": "false",
"supportedSchemes": "Mastercard",
"canPayPal`: `false`": false,
"payPalEmail": "null",
"payPalWebExperienceId": "null",
"expressCheckout": true,
"name": "PayMaya Developers Portal"
},
"totalAmount": {
"value": 100,
"currency": "PHP",
"details": {
"discount": 0,
"serviceCharge": 0,
"shippingFee": 0,
"tax": 0,
"subtotal": 100
}
},
"redirectUrl": {
"success": "https://www.merchantsite.com/success",
"failure": "https://www.merchantsite.com/failure",
"cancel": "https://www.merchantsite.com/cancel"
},
"transactionReferenceNumber": "316fb46d-5d55-465e-8f42-9fff2aaa6fa9",
"metadata": {}
}
```
#### Get Payments via RRN - GET https://pg-sandbox.paymaya.com/payments/v1/payment-rrns/:rrn
Retrieves payments matching the Request Reference Number.
> Requires secret key
> Please note the differences in the route and the response body.
> Ids from the response in the list can be used with Get Checkout API
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
[
{
"id": "e775b82b-91ee-4b12-a2a3-7e9b281ee502",
"isPaid": false,
"status": "PAYMENT_EXPIRED",
"amount": "100",
"currency": "PHP",
"canVoid": false,
"canRefund": false,
"canCapture": false,
"createdAt": "2019-02-26T14:23:37.000Z",
"updatedAt": "2019-02-26T15:23:37.000Z",
"description": "Charge for John Doe",
"metadata": {},
"requestReferenceNumber": "1551191039"
},
{
"id": "73759488-a84e-481d-97e2-cc67b528b326",
"isPaid": true,
"status": "PAYMENT_SUCCESS",
"amount": "100",
"currency": "PHP",
"canVoid": false,
"canRefund": true,
"canCapture": false,
"createdAt": "2019-02-26T14:23:57.000Z",
"updatedAt": "2019-02-26T14:25:51.000Z",
"description": "Charge for John Doe",
"paymentTokenId": "PmElRIoqh20edZuLBUXlCqLRauJ0oLzmoimkSjMSJmGDDxAcnQfKJ7fsW3OExuWBSOIU5Xp4rEutaLpHCwbx1C1gJ7M2ioHnktg7xVzx03k2hSTZ85HifflwHhXtBfq4fGPrnVOwYkxY7SlLqTjWCx1unhoYe5P4I9cjoKo",
"metadata": {},
"receiptNumber": "703717440845",
"requestReferenceNumber": "1551191039"
}
]
}
```
### Void and Refund API
#### Void by ID - POST https://pg-sandbox.paymaya.com/payments/v1/payments/:paymentId/voids
Voids a payment transaction before the 12am cutoff of the transaction date.
> Requires secret key
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
##### Body
```
{
"reason": "Incorrect item ordered."
}
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"id": "16412a59-72e7-401d-a233-cd71afccb85a",
"payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
"status": "SUCCESS",
"reason": "Incorrect item ordered.",
"createdAt": "2018-03-05T06:39:08Z",
"updatedAt": "2018-03-05T06:39:10Z"
}
```
#### Get Voids - GET https://pg-sandbox.paymaya.com/payments/v1/payments/:paymentId/voids
Retrieves a list of void transactions of a payment.
> Requires secret key
**Request**
##### Headers
```
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
[
{
"id": "16412a59-72e7-401d-a233-cd71afccb85a",
"payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
"status": "SUCCESS",
"reason": "Incorrect item ordered.",
"createdAt": "2018-03-05T06:39:08Z",
"updatedAt": "2018-03-05T06:39:10Z"
}
]
```
#### Refund by ID - POST https://pg-sandbox.paymaya.com/payments/v1/payments/:paymentId/refunds
Refunds a payment transaction after the 12am cutoff of the transaction date.
> Requires secret key
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
##### Body
```
{
"totalAmount": {
"amount": 250,
"currency": "PHP"
},
"reason": "Item out of stock"
}
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"id": "fbc7d874-4f05-45e8-b205-14e2d07657f5",
"payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
"amount": "250.00",
"currency": "PHP",
"status": "SUCCESS",
"reason": "Item out of stock",
"createdAt": "2018-03-05T06:39:08Z",
"updatedAt": "2018-03-05T06:39:10Z"
}
```
#### Get Refunds - GET https://pg-sandbox.paymaya.com/payments/v1/payments/:paymentId/refunds
Retrieves a list of refund transactions of a payment.
> Requires secret key
**Request**
##### Headers
```
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
[
{
"id": "fbc7d874-4f05-45e8-b205-14e2d07657f5",
"payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
"amount": "250.00",
"currency": "PHP",
"status": "SUCCESS",
"reason": "Item out of stock",
"createdAt": "2018-03-05T06:39:08Z",
"updatedAt": "2018-03-05T06:39:10Z"
}
]
```
## Webhooks
The PayMaya Payment Gateway supports webhooks. A webhook (also called a web callback) is a way for an application to provide other applications with real-time information. With webhooks, PayMaya sends out payment-related information to the Merchant’s set of provided URLs for internal processing/audit.
> The webhook will be triggered with an HTTP POST request with the content body equivalent to the Get Checkout API
> Webhooks are environment specific. They must be registered again on Production.
The table below lists down the webhook names for PayMaya wallet payments listed according to the status of the payment transaction:
|Webhook name|Payment status
|-|-
|CHECKOUT_SUCCESS|PAYMENT_SUCCESS
|CHECKOUT_FAILURE|PAYMENT_FAILED
|CHECKOUT_DROPOUT|PAYMENT_EXPIRED
You may register your webhook endpoints thru the Settings page on PayMaya Manager or via the APIs listed below.
For more details refer to the Webhook Guide and FAQ here
### Webhook API
#### Create Webhook - POST https://pg-sandbox.paymaya.com/checkout/v1/webhooks
Creates a webhook.
> Requires secret key
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
##### Body
```
{
"name":"CHECKOUT_SUCCESS",
"callbackUrl":"https://www.google.com"
}
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"id": "5a6ebcea-fb2e-4d0d-b144-9b022dccdb4c",
"name": "CHECKOUT_SUCCESS",
"callbackUrl": "http://www.google.com",
"createdAt": "2020-01-17T09:47:24.000Z",
"updatedAt": "2020-01-17T09:47:24.000Z"
}
```
#### Get Webhook List - GET https://pg-sandbox.paymaya.com/checkout/v1/webhooks
Gets a list of webhooks.
> Requires secret key
**Request**
##### Headers
```
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
[
{
"id": "5a6ebcea-fb2e-4d0d-b144-9b022dccdb4c",
"name": "CHECKOUT_SUCCESS",
"callbackUrl": "http://www.google.com",
"createdAt": "2020-01-17T09:47:24.000Z",
"updatedAt": "2020-01-17T09:47:24.000Z"
},
{
"id": "aeb86e67-839e-4466-9d68-7cb22d1830a9",
"name": "CHECKOUT_FAILURE",
"callbackUrl": "https://www.google.com",
"createdAt": "2020-01-16T07:20:56.000Z",
"updatedAt": "2020-01-16T07:20:56.000Z"
}
]
```
#### Delete Webhook - DELETE https://pg-sandbox.paymaya.com/checkout/v1/webhooks/:webhookId
Removes a webhook.
> Requires secret key
**Request**
##### Headers
```
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
> No Content
## Customizations
The PayMaya Payment Gateway supports customizations on select UI components. The following are the supported customizations:
> Webhooks are environment specific. They must be configured again on Production.
|Customization Name|Parameter Name|Value|Description
|-|-|-|-
|Logo Url|logoUrl|Publicly accessible link to an image|Merchant logo to be displayed, Max height is 50px
|Icon Url|iconUrl|Publicly accessible link to an image|Favicon. This is the small icon on the top of the browser page.
|Apple Touch Icon Url|appleTouchIconUrl| Publicly accessible link to an image|Favicon* for Apple Touch, 120px x 120px image
|Custom Title|customTitle|String|Changes the page title
|Color Scheme|colorScheme|Hex color code|Changes the button color
|Show Merchant Name|showMerchantName|true/false|Hides the Merchant Name underneath the logo. Use this if your logo already has your brand name
|Hide Receipt|hideReceiptInput|true/false|Hides the online receipt sending panel on the result page
|Redirect Timer|redirectTimer|Number between 3-30|Time in seconds before auto redirection on the result page
|Skip Result Page|skipResultPage|true/false|If set to true will not display the PayMaya result page. After processing it will redirect back to the Merchant website.
> Customizations only need to be setup once and not before every Checkout
You may register your customizations thru the Settings page on PayMaya Manager or via the APIs listed below
### Customization API
#### Create / Update Customization - POST https://pg-sandbox.paymaya.com/checkout/v1/customizations
Creates or updates the customizations.
> Requires secret key
**Request**
##### Headers
```
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
##### Body
```
{
"logoUrl": "https://cdn3.iconfinder.com/data/icons/diagram_v2/PNG/96x96/diagram_v2-12.png",
"iconUrl": "https://cdn3.iconfinder.com/data/icons/diagram_v2/PNG/96x96/diagram_v2-12.png",
"appleTouchIconUrl": "https://cdn3.iconfinder.com/data/icons/diagram_v2/PNG/96x96/diagram_v2-12.png",
"customTitle": "Custom Merchant",
"colorScheme": "#89D0CE",
"showMerchantName": true,
"hideReceiptInput": true,
"skipResultPage": false,
"redirectTimer": 3
}
```
**Response**
##### Headers
```
Content-Type: application/json
```
##### Body
```
{
"logoUrl": "https://cdn3.iconfinder.com/data/icons/diagram_v2/PNG/96x96/diagram_v2-12.png",
"iconUrl": "https://cdn3.iconfinder.com/data/icons/diagram_v2/PNG/96x96/diagram_v2-12.png",
"appleTouchIconUrl": "https://cdn3.iconfinder.com/data/icons/diagram_v2/PNG/96x96/diagram_v2-12.png",
"customTitle": "Custom Merchant",
"colorScheme": "#89D0CE",
"showMerchantName": true,
"hideReceiptInput": true,
"skipResultPage": false,
"redirectTimer": 3
}
```
#### Delete Customization - DELETE https://pg-sandbox.paymaya.com/checkout/v1/customizations
Removes the customizations.
> Requires secret key
**Request**
##### Headers
```
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
```
**Response**
###### Headers
```
Content-Type: application/json
```
###### Body
> No Content