![PayMaya Developers](https://cdn.paymaya.com/production/devportal/www/images/Logo_Header_v2.png) # PayMaya Payment Gateway - Payment Vault ## 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 ##### Production 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) ## Payment Statuses ```mermaid graph TD subgraph Create PP(PENDING_PAYMENT) end subgraph Authentication FA(FOR_AUTHENTICATION) AA(AUTHENTICATING) AS(AUTH_SUCCESS) AF(AUTH_FAILED) end subgraph Processing P(PAYMENT_PROCESSING) PS(PAYMENT_SUCCESS) PF(PAYMENT_FAILED) end subgraph After Sales VD(VOIDED) RF(REFUNDED) end PE(PAYMENT_EXPIRED) PP --> PE FA --> PE AA --> PE PP --> FA FA --> AA AA --> AS AA --> AF AS --> P P --> PS P --> PF PS --> VD PS --> RF ``` > Payments and Payment Tokens expire 15 mins from Creation. **Authentication for varies on the payment method used.** * Authentication for Card payments is done via 3dsecure. Depending on the card issuer, the authentication challenge may vary. * Authentication for Pay With PayMaya is done via PayMaya login and one-time pin challenge. ## One-time Payment One-time Payment is a single payment execution using a Payment Token. > Card tokenization or card information collection MUST be client-side. Card information MUST NOT pass thru the merchant server unless merchant is **PCI-DSS Certified**. ### Payment Flow ```mermaid sequenceDiagram Customer ->> Merchant: Initiate Payment Merchant -->> Customer: Get Payment Token Customer ->> Payment Gateway: Tokenize Card Payment Gateway --> Customer: Return Payment Token Customer ->> Merchant: Send Payment Token Merchant ->> Payment Gateway: Create Payment Payment Gateway -->> Merchant: Return verificationUrl Merchant -->> Customer: Redirect to webpage Customer ->> Payment Gateway: Customer completes authentication 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 ``` ### Payment API #### Create Payment Token - POST https://pg-sandbox.paymaya.com/payments/v1/payment-tokens > Requires public key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo= ``` ##### Body ``` { "card": { "number": "5123456789012346", "expMonth": "12", "expYear": "2025", "cvc": "111" } } ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "paymentTokenId": "zHaqT073VaBlLkEelWUvFOXOQPIyNSxqiyod3KfzFDVVYwVYiWauCOorsuIXQ6THsMrVVdDEPCT11vdW2PdvoaISmrfXoWRhWgwRUQyyX0hjV6sjVZ3DLmkltdUEUz6ZsFue9ka9otYM24xbrS6F7zBRYuC8W6m586G3745hg", "state": "AVAILABLE", "createdAt": "2020-05-12T14:35:59.000Z", "updatedAt": "2020-05-12T14:35:59.000Z", "issuer": "Others" } ``` #### Create Payment - POST https://pg-sandbox.paymaya.com/payments/v1/payments > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` ##### Body ``` { "paymentTokenId": "zHaqT073VaBlLkEelWUvFOXOQPIyNSxqiyod3KfzFDVVYwVYiWauCOorsuIXQ6THsMrVVdDEPCT11vdW2PdvoaISmrfXoWRhWgwRUQyyX0hjV6sjVZ3DLmkltdUEUz6ZsFue9ka9otYM24xbrS6F7zBRYuC8W6m586G3745hg", "totalAmount": { "amount": 100, "currency": "PHP" }, "buyer": { "firstName": "John", "middleName": "Paul", "lastName": "Doe", "birthday": "1995-10-24", "customerSince": "1995-10-24", "sex": "M", "contact": { "phone": "+639181008888", "email": "merchant@merchantsite.com" }, "shippingAddress": { "firstName": "John", "middleName": "Paul", "lastName": "Doe", "phone": "+639181008888", "email": "merchant@merchantsite.com", "line1": "6F Launchpad", "line2": "Reliance Street", "city": "Mandaluyong City", "state": "Metro Manila", "zipCode": "1552", "countryCode": "PH", "shippingType": "ST" // ST - for standard, SD - for same day }, "billingAddress": { "line1": "6F Launchpad", "line2": "Reliance Street", "city": "Mandaluyong City", "state": "Metro Manila", "zipCode": "1552", "countryCode": "PH" } }, "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 ``` { "id": "a6ca41fc-9e54-4b99-b447-9215fb7ef9d1", "isPaid": false, "status": "FOR_AUTHENTICATION", "amount": "100", "currency": "PHP", "canVoid": false, "canRefund": false, "canCapture": false, "createdAt": "2020-05-12T14:37:31.000Z", "updatedAt": "2020-05-12T14:37:32.000Z", "description": "Charge for merchant@merchantsite.com", "paymentTokenId": "zHaqT073VaBlLkEelWUvFOXOQPIyNSxqiyod3KfzFDVVYwVYiWauCOorsuIXQ6THsMrVVdDEPCT11vdW2PdvoaISmrfXoWRhWgwRUQyyX0hjV6sjVZ3DLmkltdUEUz6ZsFue9ka9otYM24xbrS6F7zBRYuC8W6m586G3745hg", "metadata": {}, "requestReferenceNumber": "1551191039", "verificationUrl": "https://payments-web-sandbox.paymaya.com/authenticate?id=a6ca41fc-9e54-4b99-b447-9215fb7ef9d1" } ``` > For Risk Management Solution the entire buyer object is required. #### Get Payment - GET https://pg-sandbox.paymaya.com/payments/v1/payments/:paymentId Retrieves a Payment. > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "id": "a6ca41fc-9e54-4b99-b447-9215fb7ef9d1", "isPaid": true, "status": "PAYMENT_SUCCESS", "amount": "100", "currency": "PHP", "canVoid": true, "canRefund": false, "canCapture": false, "createdAt": "2020-05-12T14:37:31.000Z", "updatedAt": "2020-05-12T14:41:32.000Z", "description": "Charge for merchant@merchantsite.com", "paymentTokenId": "zHaqT073VaBlLkEelWUvFOXOQPIyNSxqiyod3KfzFDVVYwVYiWauCOorsuIXQ6THsMrVVdDEPCT11vdW2PdvoaISmrfXoWRhWgwRUQyyX0hjV6sjVZ3DLmkltdUEUz6ZsFue9ka9otYM24xbrS6F7zBRYuC8W6m586G3745hg", "fundSource": { "type": "card", "id": "zHaqT073VaBlLkEelWUvFOXOQPIyNSxqiyod3KfzFDVVYwVYiWauCOorsuIXQ6THsMrVVdDEPCT11vdW2PdvoaISmrfXoWRhWgwRUQyyX0hjV6sjVZ3DLmkltdUEUz6ZsFue9ka9otYM24xbrS6F7zBRYuC8W6m586G3745hg", "description": "**** **** **** 2346", "details": { "scheme": "master-card", "last4": "2346", "first6": "512345", "masked": "512345******2346", "issuer": "Others" } }, "receipt": { "transactionId": "d3f0a905-160e-46f7-8190-c938e9aca1ab", "receiptNo": "b2ba3089beef", "approval_code": "00001234", "approvalCode": "00001234" }, "metadata": {}, "approvalCode": "00001234", "receiptNumber": "b2ba3089beef", "requestReferenceNumber": "1551191039" } ``` ## Customer Payments Customer Payments save the Customer's card information to a customer record. This allows the merchant charge additional payments without re-collecting card information. > Card tokenization or card information collection MUST be client-side. Card information MUST NOT pass thru the merchant server unless merchant is **PCI-DSS Certified**. ### Card Linking Flow ```mermaid sequenceDiagram Customer ->> Merchant: Sign up as user Merchant ->> Payment Gateway: Create Customer record Payment Gateway -->> Merchant: Return Customer Id Merchant -->> Customer: Customer ->> Merchant: Initiate Payment Merchant -->> Customer: Get Payment Token Customer ->> Payment Gateway: Tokenize Card Payment Gateway --> Customer: Return Payment Token Customer ->> Merchant: Send Payment Token Merchant ->> Payment Gateway: Link Payment Token to Customer Payment Gateway -->> Merchant: Return verificationUrl Merchant -->> Customer: Redirect to webpage Customer ->> Payment Gateway: Customer completes authentication 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 Merchant ->> Payment Gateway: Create Customer Payment Payment Gateway -->> Merchant: Return Payment ``` > Card linking will charge a PHP 10 test fee. This fee is auto-voided on successful linking. > Succeeding Customer Payments no longer passes thru the authentication flow. > For added security, 3ds authentication can be turned on for Customer Payments. ### Card Link and Charge Flow ```mermaid sequenceDiagram Customer ->> Merchant: Sign up as user Merchant ->> Payment Gateway: Create Customer record Payment Gateway -->> Merchant: Return Customer Id Merchant -->> Customer: Customer ->> Merchant: Initiate Payment Merchant -->> Customer: Get Payment Token Customer ->> Payment Gateway: Tokenize Card Payment Gateway --> Customer: Return Payment Token Customer ->> Merchant: Send Payment Token Merchant ->> Payment Gateway: Link Payment Token to Customer Payment Gateway -->> Merchant: Return verificationUrl Merchant ->> Payment Gateway: Create Customer Payment Payment Gateway -->> Merchant: Return verificationUrl Merchant -->> Customer: Redirect to webpage Customer ->> Payment Gateway: Customer completes authentication 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 Merchant ->> Payment Gateway: Create Customer Payment Payment Gateway -->> Merchant: Return Payment ``` > This flow will cancel the 10 pesos test fee Payment and will use the Merchant created Payment to validate the card linking. > Succeeding Customer Payments no longer passes thru the authentication flow. > For added security, 3ds authentication can be turned on for Customer Payments. ### Customer API #### Create Customer - POST https://pg-sandbox.paymaya.com/payments/v1/customers > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` ##### Body ``` { "firstName": "John", "middleName": "Paul", "lastName": "Doe", "birthday": "1995-10-24", "customerSince": "1995-10-24", "sex": "M", "contact": { "phone": "+639181008888", "email": "merchant@merchantsite.com" }, "shippingAddress": { "firstName": "John", "middleName": "Paul", "lastName": "Doe", "phone": "+639181008888", "email": "merchant@merchantsite.com", "line1": "6F Launchpad", "line2": "Reliance Street", "city": "Mandaluyong City", "state": "Metro Manila", "zipCode": "1552", "countryCode": "PH", "shippingType": "ST" // ST - for standard, SD - for same day }, "billingAddress": { "line1": "6F Launchpad", "line2": "Reliance Street", "city": "Mandaluyong City", "state": "Metro Manila", "zipCode": "1552", "countryCode": "PH" } } ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "id": "df494249-e67e-4b37-ab9d-49f8a8194bd6", "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" }, "sex": "M", "birthday": "1995-10-24", "createdAt": "2020-05-12T14:55:01.000Z", "updatedAt": "2020-05-12T14:55:01.000Z" } ``` #### Update Customer - PUT https://pg-sandbox.paymaya.com/payments/v1/customers/:customerId > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` ##### Body ``` { "firstName": "John", "middleName": "Michael", "lastName": "Doe", } ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "id": "df494249-e67e-4b37-ab9d-49f8a8194bd6", "firstName": "John", "middleName": "Michael", "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" }, "sex": "M", "birthday": "1995-10-24", "createdAt": "2020-05-12T14:55:01.000Z", "updatedAt": "2020-05-12T14:55:01.000Z" } ``` #### Get Customer - GET https://pg-sandbox.paymaya.com/payments/v1/customers/:customerId > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "id": "df494249-e67e-4b37-ab9d-49f8a8194bd6", "firstName": "John", "middleName": "Michael", "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" }, "sex": "M", "birthday": "1995-10-24", "createdAt": "2020-05-12T14:55:01.000Z", "updatedAt": "2020-05-12T14:55:01.000Z" } ``` #### Delete Customer - DELETE https://pg-sandbox.paymaya.com/payments/v1/customers/:customerId > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "id": "df494249-e67e-4b37-ab9d-49f8a8194bd6", "firstName": "John", "middleName": "Michael", "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" }, "sex": "M", "birthday": "1995-10-24", "createdAt": "2020-05-12T14:55:01.000Z", "updatedAt": "2020-05-12T14:55:01.000Z" } ``` ### Customer Payment API #### Link Card to Customer - POST https://pg-sandbox.paymaya.com/payments/v1/customers/:customerId/cards > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` ##### Body ``` { "paymentTokenId": "fIOA0DxV0WIqt4ij2qHa3ZCLKJks5A7th8Y7p8h4HK0zfipKRTtEV26sovKwbDaGwYPPsFelV2lJkrsBhvFJoary56nHjGWAGKPKn7E3XfD1pBDPv6m34V8uu1cdwSVOMiEsZlVdoMd7IR8Te124jnIdOIfqTvhO1lMDdk", "isDefault": true, "redirectUrl": { "success": "https://www.merchantsite.com/success", "failure": "https://www.merchantsite.com/failure", "cancel": "https://www.merchantsite.com/cancel" } } ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "cardTokenId": "fIOA0DxV0WIqt4ij2qHa3ZCLKJks5A7th8Y7p8h4HK0zfipKRTtEV26sovKwbDaGwYPPsFelV2lJkrsBhvFJoary56nHjGWAGKPKn7E3XfD1pBDPv6m34V8uu1cdwSVOMiEsZlVdoMd7IR8Te124jnIdOIfqTvhO1lMDdk", "cardType": "master-card", "maskedPan": "2346", "createdAt": "2020-05-12T15:02:32.000Z", "updatedAt": "2020-05-12T15:02:32.000Z", "id": "160262a8-f8b8-4631-94eb-7dc35dc7ca00", "state": "PREVERIFICATION", "default": true, "verificationUrl": "https://payments-web-sandbox.paymaya.com/authenticate?id=160262a8-f8b8-4631-94eb-7dc35dc7ca00" } ``` #### Get Customer Cards - GET https://pg-sandbox.paymaya.com/payments/v1/customers/:customerId/cards > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` [ { "first6": "512345", "last4": "2346", "cardTokenId": "fIOA0DxV0WIqt4ij2qHa3ZCLKJks5A7th8Y7p8h4HK0zfipKRTtEV26sovKwbDaGwYPPsFelV2lJkrsBhvFJoary56nHjGWAGKPKn7E3XfD1pBDPv6m34V8uu1cdwSVOMiEsZlVdoMd7IR8Te124jnIdOIfqTvhO1lMDdk", "cardType": "master-card", "maskedPan": "2346", "createdAt": "2020-05-12T15:02:32.000Z", "updatedAt": "2020-05-12T15:07:54.000Z", "walletType": "VAULTED", "state": "VERIFIED", "default": false }, { "first6": "512345", "last4": "2346", "cardTokenId": "HSuY429VtYwZMXaJuZujP9opteud0iKMmXSt80JiKkeJRIPnMjdrG3YqvFDEaK9KegUMzp44fw0GdKATAyYkMLExjuhSr9FEsfrY4ngLWxO9RPR2lb0e3F2Xk3J4gPyFreaQwxvcVNpMIPFttmE3Z4BuaNgbhR15eOK0Q", "cardType": "master-card", "maskedPan": "2346", "createdAt": "2020-05-12T15:07:54.000Z", "updatedAt": "2020-05-12T15:07:54.000Z", "walletType": "VAULTED", "state": "VERIFIED", "default": true } ] ``` #### Get Customer Card - GET https://pg-sandbox.paymaya.com/payments/v1/customers/:customerId/cards/:paymentToken > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "first6": "512345", "last4": "2346", "cardTokenId": "fIOA0DxV0WIqt4ij2qHa3ZCLKJks5A7th8Y7p8h4HK0zfipKRTtEV26sovKwbDaGwYPPsFelV2lJkrsBhvFJoary56nHjGWAGKPKn7E3XfD1pBDPv6m34V8uu1cdwSVOMiEsZlVdoMd7IR8Te124jnIdOIfqTvhO1lMDdk", "cardType": "master-card", "maskedPan": "2346", "createdAt": "2020-05-12T15:02:32.000Z", "updatedAt": "2020-05-12T15:02:32.000Z", "walletType": "VAULTED", "state": "VERIFIED", "default": true } ``` #### Update Customer Card - PUT https://pg-sandbox.paymaya.com/payments/v1/customers/:customerId/cards/:paymentToken > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` ##### Body ``` { "isDefault": true } ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "first6": "512345", "last4": "2346", "cardTokenId": "fIOA0DxV0WIqt4ij2qHa3ZCLKJks5A7th8Y7p8h4HK0zfipKRTtEV26sovKwbDaGwYPPsFelV2lJkrsBhvFJoary56nHjGWAGKPKn7E3XfD1pBDPv6m34V8uu1cdwSVOMiEsZlVdoMd7IR8Te124jnIdOIfqTvhO1lMDdk", "cardType": "master-card", "maskedPan": "2346", "createdAt": "2020-05-12T15:02:32.000Z", "updatedAt": "2020-05-12T15:02:32.000Z", "walletType": "VAULTED", "state": "VERIFIED", "default": true } ``` #### Delete Customer Card - DELETE https://pg-sandbox.paymaya.com/payments/v1/customers/:customerId/cards/:paymentToken > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "first6": "512345", "last4": "2346", "cardTokenId": "fIOA0DxV0WIqt4ij2qHa3ZCLKJks5A7th8Y7p8h4HK0zfipKRTtEV26sovKwbDaGwYPPsFelV2lJkrsBhvFJoary56nHjGWAGKPKn7E3XfD1pBDPv6m34V8uu1cdwSVOMiEsZlVdoMd7IR8Te124jnIdOIfqTvhO1lMDdk", "cardType": "master-card", "maskedPan": "2346", "createdAt": "2020-05-12T15:02:32.000Z", "updatedAt": "2020-05-12T15:02:32.000Z", "walletType": "VAULTED", "state": "VERIFIED", "default": true } ``` #### Create Customer Payment - POST https://pg-sandbox.paymaya.com/payments/v1/customers/:customerId/cards/:paymentToken/payments > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` ##### Body ``` { "totalAmount": { "amount": 100, "currency": "PHP" } } ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "id": "5682dbb8-74cf-40ad-9bb9-2dc63d04bbe9", "isPaid": true, "status": "PAYMENT_SUCCESS", "amount": "100", "currency": "PHP", "canVoid": true, "canRefund": false, "canCapture": false, "createdAt": "2020-05-12T15:12:24.000Z", "updatedAt": "2020-05-12T15:12:24.000Z", "description": "Charge for merchant@merchantsite.com", "paymentTokenId": "fIOA0DxV0WIqt4ij2qHa3ZCLKJks5A7th8Y7p8h4HK0zfipKRTtEV26sovKwbDaGwYPPsFelV2lJkrsBhvFJoary56nHjGWAGKPKn7E3XfD1pBDPv6m34V8uu1cdwSVOMiEsZlVdoMd7IR8Te124jnIdOIfqTvhO1lMDdk", "fundSource": { "type": "card", "id": "fIOA0DxV0WIqt4ij2qHa3ZCLKJks5A7th8Y7p8h4HK0zfipKRTtEV26sovKwbDaGwYPPsFelV2lJkrsBhvFJoary56nHjGWAGKPKn7E3XfD1pBDPv6m34V8uu1cdwSVOMiEsZlVdoMd7IR8Te124jnIdOIfqTvhO1lMDdk", "description": "**** **** **** 2346", "details": { "scheme": "master-card", "last4": "2346", "first6": "512345", "masked": "512345******2346", "issuer": "Others" } }, "receipt": { "transactionId": "749f27f4-daac-45a4-bd41-798c85782111", "receiptNo": "0d703b6c9d3e", "approval_code": "00001234", "approvalCode": "00001234" }, "approvalCode": "00001234", "receiptNumber": "0d703b6c9d3e" } ``` ## Subscription Payments Subscription Payments will set a scheduled recurring charge on a Linked Customer Card Intervals: * DAY * MONTH * YEAR Interval Count is the number of intervals before the next recurrance is run. Subscriptions will attempt to charge on the given schedule at `11:00 PM`. If the payment fails, the subscription will be set to inactive. Inactive Subscriptions will not charge. #### Create Subscription - POST https://pg-sandbox.paymaya.com/payments/v1/customers/:customerId/cards/:paymentToken/subscriptions > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` ##### Body ``` { "description": "Sample subscription", "totalAmount": { "amount": "1.00", "currency": "PHP" }, "interval": "DAY", "intervalCount": 1, "startDate": "2020-05-21" } ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "id": "98771648-81ad-4ea0-b469-63146b944ccc", "description": "Sample subscription", "status": "ACTIVE", "amount": "1", "currency": "PHP", "interval": "DAY", "metadata": null, "intervalCount": 1, "startDate": "2020-05-21T00:00:00.000Z", "endDate": null, "cancelledAt": null, "createdAt": "2020-05-12T15:17:16.000Z", "updatedAt": "2020-05-12T15:17:16.000Z" } ``` #### Get Customer Subscription - GET https://pg-sandbox.paymaya.com/payments/v1/customers/:customerId/cards/:paymentToken/subscriptions > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` [ { "id": "98771648-81ad-4ea0-b469-63146b944ccc", "description": "Sample subscription", "status": "ACTIVE", "amount": "1", "currency": "PHP", "interval": "DAY", "metadata": null, "intervalCount": 1, "startDate": "2020-05-21T00:00:00.000Z", "endDate": null, "cancelledAt": null, "createdAt": "2020-05-12T15:17:16.000Z", "updatedAt": "2020-05-12T15:17:16.000Z" }, { "id": "ae5150be-25b8-4cd6-a73c-61981d020365", "description": "Sample quarterly subscription", "status": "ACTIVE", "amount": "1", "currency": "PHP", "interval": "MONTH", "metadata": null, "intervalCount": 3, "startDate": "2020-05-21T00:00:00.000Z", "endDate": null, "cancelledAt": null, "createdAt": "2020-05-12T15:21:43.000Z", "updatedAt": "2020-05-12T15:21:43.000Z" } ] ``` #### Get Subscription - GET https://pg-sandbox.paymaya.com/payments/v1/subscriptions/:subscriptionId > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "id": "98771648-81ad-4ea0-b469-63146b944ccc", "description": "Sample subscription", "status": "ACTIVE", "amount": "1", "currency": "PHP", "interval": "DAY", "metadata": null, "intervalCount": 1, "startDate": "2020-05-21T00:00:00.000Z", "endDate": null, "cancelledAt": null, "createdAt": "2020-05-12T15:17:16.000Z", "updatedAt": "2020-05-12T15:17:16.000Z" } ``` #### Cancel Subscription - DELETE https://pg-sandbox.paymaya.com/payments/v1/subscriptions/:subscriptionId > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "id": "98771648-81ad-4ea0-b469-63146b944ccc", "description": "Sample subscription", "status": "CANCELLED", "amount": "1", "currency": "PHP", "interval": "DAY", "metadata": null, "intervalCount": 1, "startDate": "2020-05-21T00:00:00.000Z", "endDate": null, "cancelledAt": null, "createdAt": "2020-05-12T15:17:16.000Z", "updatedAt": "2020-05-12T15:24:08.000Z" } ``` #### Get Subscription Payments - DELETE https://pg-sandbox.paymaya.com/payments/v1/subscriptions/:subscriptionId/payments > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` [ { "id": "5682dbb8-74cf-40ad-9bb9-2dc63d04bbe9", "subscription": "98771648-81ad-4ea0-b469-63146b944ccc" "isPaid": true, "status": "PAYMENT_SUCCESS", "amount": "100", "currency": "PHP", "canVoid": true, "canRefund": false, "canCapture": false, "createdAt": "2020-22-12T15:12:24.000Z", "updatedAt": "2020-22-12T15:12:24.000Z", "description": "Charge for merchant@merchantsite.com", "paymentTokenId": "fIOA0DxV0WIqt4ij2qHa3ZCLKJks5A7th8Y7p8h4HK0zfipKRTtEV26sovKwbDaGwYPPsFelV2lJkrsBhvFJoary56nHjGWAGKPKn7E3XfD1pBDPv6m34V8uu1cdwSVOMiEsZlVdoMd7IR8Te124jnIdOIfqTvhO1lMDdk", "fundSource": { "type": "card", "id": "fIOA0DxV0WIqt4ij2qHa3ZCLKJks5A7th8Y7p8h4HK0zfipKRTtEV26sovKwbDaGwYPPsFelV2lJkrsBhvFJoary56nHjGWAGKPKn7E3XfD1pBDPv6m34V8uu1cdwSVOMiEsZlVdoMd7IR8Te124jnIdOIfqTvhO1lMDdk", "description": "**** **** **** 2346", "details": { "scheme": "master-card", "last4": "2346", "first6": "512345", "masked": "512345******2346", "issuer": "Others" } }, "receipt": { "transactionId": "749f27f4-daac-45a4-bd41-798c85782111", "receiptNo": "0d703b6c9d3e", "approval_code": "00001234", "approvalCode": "00001234" }, "approvalCode": "00001234", "receiptNumber": "0d703b6c9d3e" } ] ``` ## 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 |-|- |PAYMENT_SUCCESS|PAYMENT_SUCCESS |PAYMENT_FAILED|PAYMENT_FAILED |PAYMENT_EXPIRED|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":"PAYMENT_SUCCESS", "callbackUrl":"https://www.google.com" } ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "id": "5a6ebcea-fb2e-4d0d-b144-9b022dccdb4c", "name": "PAYMENT_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": "PAYMENT_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 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 ## Manual Capture ### Payment Flow ```mermaid sequenceDiagram Customer ->> Merchant: Initiate Payment Merchant -->> Customer: Get Payment Token Customer ->> Payment Gateway: Tokenize Card Payment Gateway --> Customer: Return Payment Token Customer ->> Merchant: Send Payment Token Merchant ->> Payment Gateway: Create Payment Payment Gateway -->> Merchant: Return verificationUrl Merchant -->> Customer: Redirect to webpage Customer ->> Payment Gateway: Customer completes authentication 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 Merchant ->> Payment Gateway: Capture Payment ``` ### Authorization Payment Statuses ```mermaid graph TD subgraph Create PT(PENDING_TOKEN) PP(PENDING_PAYMENT) end subgraph Authentication FA(FOR_AUTHENTICATION) AA(AUTHENTICATING) AS(AUTH_SUCCESS) AF(AUTH_FAILED) end subgraph Processing P(PAYMENT_PROCESSING) PS(AUTHORIZED) PF(PAYMENT_FAILED) C(CAPTURED) D(DONE) CHE(CAPTURE_HOLD_EXPIRED) end subgraph After Sales VD(VOIDED) end PE(PAYMENT_EXPIRED) PT --> PE PP --> PE FA --> PE AA --> PE PT --> PP PP --> FA FA --> AA AA --> AS AA --> AF AS --> P P --> PS P --> PF PS --> C C --> D PS --> VD PS --> CHE ``` ### Capture Payment Statuses ```mermaid graph TD subgraph P(PENDING_PAYMENT) PS(PAYMENT_SUCCESS) PF(PAYMENT_FAILED) end subgraph After Sales VD(VOIDED) RD(REFUNDED) end P --> PS P --> PF PS --> VD PS --> RD ``` #### Authorization Types **NORMAL** Indicates a Normal Authorization transaction, this authorization request can be captured and cleared for amounts less than or equal to the authorization amount. **FINAL** Indicates a Final Authorization transaction, this authorization request can be only be captured and cleared for amounts equal to the authorization amount (i.e., partial captures are not supported). **PREAUTHORIZATION** Indicates a Preauthorization transaction, this authorization request can be captured and cleared for amounts greater than (not yet supported), less than, or equal to the authorization amount. On certain conditions, a preauthorization may have longer hold periods than normal authorizations. Please refer to Authorization Hold Periods for more details. > This is included in the Create Checkout API as > `"authorizationType": "NORMAL" / "FINAL" / "PREAUTHORIZATION"` ##### Sample Body ``` { "authorizationType": "NORMAL", "paymentTokenId": "zHaqT073VaBlLkEelWUvFOXOQPIyNSxqiyod3KfzFDVVYwVYiWauCOorsuIXQ6THsMrVVdDEPCT11vdW2PdvoaISmrfXoWRhWgwRUQyyX0hjV6sjVZ3DLmkltdUEUz6ZsFue9ka9otYM24xbrS6F7zBRYuC8W6m586G3745hg", "totalAmount": { "amount": 100, "currency": "PHP" }, "buyer": { "firstName": "John", "middleName": "Paul", "lastName": "Doe", "birthday": "1995-10-24", "customerSince": "1995-10-24", "sex": "M", "contact": { "phone": "+639181008888", "email": "merchant@merchantsite.com" }, "shippingAddress": { "firstName": "John", "middleName": "Paul", "lastName": "Doe", "phone": "+639181008888", "email": "merchant@merchantsite.com", "line1": "6F Launchpad", "line2": "Reliance Street", "city": "Mandaluyong City", "state": "Metro Manila", "zipCode": "1552", "countryCode": "PH", "shippingType": "ST" // ST - for standard, SD - for same day }, "billingAddress": { "line1": "6F Launchpad", "line2": "Reliance Street", "city": "Mandaluyong City", "state": "Metro Manila", "zipCode": "1552", "countryCode": "PH" } }, "redirectUrl": { "success": "https://www.merchantsite.com/success", "failure": "https://www.merchantsite.com/failure", "cancel": "https://www.merchantsite.com/cancel" }, "requestReferenceNumber": "1551191039", "metadata": {} } ``` #### Authorization Hold Periods A successful Authorization is saved (held) until the transaction is not past its hold period. Authorizations past their corresponding hold period that do not have successful captures, or were not voided, will result to the authorization hold being dropped. > Payments will be left in AUTHORIZED state. Attempting to capture will transition to CAPTURE_HOLD_EXPIRED The following table summarizes the authorization hold periods defined depending on certain conditions: | Scheme | Normal Authorization Hold Period | Final Authorization Hold Period | Pre-Authorization Hold Period |-|-|-|- | MasterCard | 6 days | 6 days | 29 days | Visa | 6 days | 6 days | 6 days / 29 days* | JCB | 6 days | 6 days | 6 days > For Visa, pre-authorized transactions can have longer hold periods (29 days) if the following conditions are met: > Merchant falls under one of the ff categories: > * Lodging (e.g. hotels, resorts, lodging reservation systems) > * Vehicle Rental > * Cruise Lines #### Capture API #### Capture - POST https://pg-sandbox.paymaya.com/payments/v1/payments/:paymentId/capture Captures an `AUTHORIZED` or `CAPTURED` payment. This will create a new payment record. This payment record can be voided or refunded. > Requires secret key **Request** ##### Headers ``` Content-Type: application/json Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo= ``` ##### Body ``` { "captureAmount": { "amount": 100, "currency": "PHP" } } ``` **Response** ##### Headers ``` Content-Type: application/json ``` ##### Body ``` { "id" : "a9254c70-410d-43d5-a55b-9043ec2beb5e", "isPaid" : false, "status" : "CAPTURED", "amount" : "2", "currency" : "PHP", "canVoid" : false, "canRefund" : false, "canCapture" : true, "createdAt" : "2020-05-13T08:54:05.000Z", "updatedAt" : "2020-05-13T08:54:10.000Z", "authorizationType" : "NORMAL", "capturedAmount" : "1", "fundSource" : { "type" : "card", "id" : "kOLUCbPgjet0aWeT48DhmD02jlKyQOWYUxpleEvXu4fTkq4NuDQzvzrWeQTLsQQNoaU23r3mnpjobsXMQdBa7HiOlU2b1LZaXnVTFxMJYuQbMXip8ZaGAm0q5jAU9ZhBpZWXqh1I8ByzgR3uMeHN9X49rZB6C2IvyXK8tAw", "description" : "**** **** **** 1112", "details" : { "scheme" : "visa", "last4" : "1112", "first6" : "401200", "masked" : "401200******1112", "issuer" : "Others" } }, "receipt" : { "transactionId" : "300134320440716", "batchNo" : "20200513", "receiptNo" : "013408151071", "approval_code" : "024871", "approvalCode" : "024871" }, "approvalCode" : "024871", "receiptNumber" : "013408151071", "requestReferenceNumber" : "PGQE-CVAS-AUTH", "capturedPaymentId" : "6b1b1e87-7608-4522-80be-ea18dac6c68d" } ``` #### Transition rules ##### Capture The first capture of an `AUTHORIZED` payment will transition the state to `CAPTURED`. Additional captures can be done while on this state. At `11:59 PM of the day the first Capture was made` the payment will transition to `DONE`. Captures can no longer be done at this state. ##### Voiding Authorization Payment Voiding an `AUTHORIZED` payment will release the capture hold and change the payment state to `VOIDED` ##### Void and Refund Captured Payment Voiding a `PAYMENT_SUCCESS` Capture payment will change the status to `VOIDED`. Voiding all Capture payments of a `CAPTURED` payment will revert the state to `AUTHORIZED`. The capture cut-off will no longer apply. `PAYMENT_SUCCESS` Capture payments can be refunded after the 12am cut-off time. ##### Webhooks `AUTHORIZED` Payments do not fire the `PAYMENT_SUCCESS` webhook. `PAYMENT_SUCCESS` Capture Payments fire the the `PAYMENT_SUCCESS` webhook. --- ##### Thank you for reading this document :3 > Last updated on 5/12/2020