Webhooks - Payment Solutions

📘

Are webhooks required?

Yes, webhooks are required when integrating your application with our services. This is to ensure payment statuses are communicated to your application in real-time.

Maya Business Payment Solutions 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, Maya sends out payment-related information to the Merchant’s set of provided URLs for internal processing/audit.

Step 1 How to receive payment information via webhook notification

Create an HTTP POST endpoint that will receive a JSON body. You may see the sample JSON body under the Payment Status table below.

This HTTP POST endpoint should respond with a HTTP 2xx status code.

const express = require('express');
const app = express();

app.post('/webhook', async (req, res) => {
  // TODO: You will have to implement the logic of this method.
  processMayaWebhookNotificationData(req.body);
  
  res.send({
    success: true
  })
});

app.listen(8080, () => console.log(`Listening on port ${8080}!`));

📘

Webhooks are environment-specific. They must be registered again in Production.

Payment Status

The table below lists the webhook names for Maya Payment Solutions. These are listed according to the status of the payment transaction:

Check out sample webhook responses here.

📘

Payment Solutions' webhook will trigger a maximum of 4 times.

• Immediately after the status event is triggered
• 5 minutes after the previous webhook call failed
• 15 minutes after the previous webhook call failed
• 45 minutes after previous webhook call failed

Step 2 Testing your webhook

Via a curl command

It is a good habit to test your webhook before saving it in Maya Business Manager or via Create Webhook endpoint.

🚧

Webhook requirements

A webhook should be SSL-secured (https) and publicly available.

It is also recommended to use port 443 for your SSL configuration. Your application may experience network issues when integrating with Maya using non-standard ports.

You can execute your webhook endpoint via a simple curl command or through an API client application like Postman.

Below is an example using a curl command. Do note that the request body and the webhook url you see below are just examples.

$ curl -s -D - -o /dev/null -X POST -H "Content-Type: application/json" \
-d '{
  "id": "fa4da2ff-dcda-4367-a97d-0c9445147b73",
  "items": [
    {
      "name": "Canvas Slip Ons",
      "code": "CVG-096732",
      "description": "Shoes",
      "quantity": "1",
      "amount": {
        "value": 1000
      },
      "totalAmount": {
        "value": 1000
      }
    }
  ],
  "requestReferenceNumber": "5fc10b93-bdbd-4f31-b31d-4575a3785009",
  "receiptNumber": "7fa0ff6fa5a6",
  "createdAt": "2021-07-13T15:25:45.000Z",
  "updatedAt": "2021-07-13T15:26:49.000Z",
  "paymentScheme": "master-card",
  "expressCheckout": true,
  "refundedAmount": "0",
  "canPayPal": false,
  "expiredAt": "2021-07-13T16:25:45.000Z",
  "status": "COMPLETED",
  "paymentStatus": "PAYMENT_SUCCESS",
  "paymentDetails": {
    "responses": {
      "efs": {
        "paymentTransactionReferenceNo": "0bea058b-ae8e-4bfc-90d0-7fa0ff6fa5a6",
        "status": "SUCCESS",
        "receipt": {
          "transactionId": "b8bb70e1-f44f-4db3-bcb9-a939d38455a4",
          "receiptNo": "7fa0ff6fa5a6",
          "approval_code": "00001234",
          "approvalCode": "00001234"
        },
        "payer": {
          "fundingInstrument": {
            "card": {
              "cardNumber": "542482******7140",
              "expiryMonth": 9,
              "expiryYear": "2023"
            }
          }
        },
        "amount": {
          "total": {
            "currency": "PHP",
            "value": 1000
          }
        },
        "created_at": "2021-07-13T15:26:49.514Z"
      }
    },
    "paymentAt": "2021-07-13T15:26:49.000Z",
    "3ds": false
  },
  "buyer": {
    "contact": {
      "phone": "+639086216587",
      "email": "[email protected]"
    },
    "firstName": "Francis Gerard",
    "lastName": "Gonzales",
    "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"
    }
  },
  "merchant": {
    "currency": "PHP",
    "email": "[email protected]",
    "locale": "en",
    "homepageUrl": "https://www.paymaya.com",
    "isEmailToMerchantEnabled": true,
    "isEmailToBuyerEnabled": true,
    "isPaymentFacilitator": false,
    "isPageCustomized": true,
    "supportedSchemes": [
      "Visa",
      "Mastercard",
      "JCB"
    ],
    "canPayPal": false,
    "payPalEmail": null,
    "payPalWebExperienceId": null,
    "expressCheckout": true,
    "name": "Omni Merchant via Mock Processor"
  },
  "totalAmount": {
    "amount": "1000",
    "currency": "PHP",
    "details": {
      "discount": "100.00",
      "serviceCharge": "0.00",
      "shippingFee": "200.00",
      "tax": "120.00",
      "subtotal": "780.00"
    }
  },
  "redirectUrl": {
    "success": "https://www.merchantsite.com/success?id=5fc10b93-bdbd-4f31-b31d-4575a3785009",
    "failure": "https://www.mechantsite.com/failure?id=5fc10b93-bdbd-4f31-b31d-4575a3785009",
    "cancel": "https://www.merchantsite.com/cancel?id=5fc10b93-bdbd-4f31-b31d-4575a3785009"
  },
  "transactionReferenceNumber": "0bea058b-ae8e-4bfc-90d0-7fa0ff6fa5a6"
}' \
https://83ef-130-105-160-253.ngrok.io/webhook

When the output of the curl command shows a 200 response code that means that your webhook reachable and will return a status 200 OK. See sample curl response below

HTTP/2 200
content-type: application/json; charset=utf-8
date: Mon, 14 Feb 2022 01:08:14 GMT
ngrok-agent-ips: 130.105.160.253
content-length: 18

Via Maya Business Manager

You can also test your webhook without saving it using your Maya Business Manager account.

1. Click Settings on the left-hand navigation and click Webhooks.
2. If you are managing multiple merchants, choose which merchant the webhook will be assigned to.
3. Paste the webhook URL in the field and click Test.

4. Manager will send a test payload to your webhook upon clicking Test. The testing will inform you if your webhook is reachable and will return a HTTP 200.

5. Once validated to be working as expected, you can now save the webhook immediately by clicking the Save and Test button.

Step 3 Registering your webhook

You may register your webhook endpoints via Maya Business Manager under Settings or via the Create Webhook endpoint.

Webhooks created via Create Webhook endpoint appear in Maya Business Manager under Settings.

Do you have any questions? Check out our Webhook FAQ.