How to use your own payment webhook?

If you have built your own integration in your in-house application with any of the payment providers, you can use our “Webhook” feature in custom payment methods. Once enabled, MGR will forward the payment request, made with this payment method, to your application.

WEBHOOK SETUP:

Webhook payments need a few parameters to be set up as below.

1. Webhook URL: The main URL of a webpage that handles the payment process in your application.
2. Username: Only required if your application requires authentication.
3. Password: Only required if your application requires authentication.
4. MGR Passcode: This should be a secure keyword or passphrase that your web page must match and verify before proceeding with the payment. This parameter is required.

How does this work?

When this payment method is selected in the payment interface within MGR, MGR will forward the request to the URL specified in the “Webhook URL“. User will be advised about the process accordingly in a popup dialogue which will stay on until the payment process finishes at your end. Your page should be handling any further payment processing. Please take a look at the following workflow.

MGR > YOUR APPLICATION

MGR will use the “POST” method to make asynchronous request to the Webhook URL with the following JSON body/data

{
  "amount": 0,
  "customer_uuid": "35-digit-uuid-xxxx-xxx-xxx",
  "payment_uuid": "35-digit-uuid-xxxx-xxx-xxx"
}

This request will contain the following headers

Content-Type: application/json
X-MGR-PASSCODE: {MGR Passcode}

With this synchronous request, MGR will wait for a “202 Accepted” status code to determine the acknowledgement from your application. Any other status code will be considered as a failure of fulfilling the request, which will terminate the payment process at MGR.

YOUR APPLICATION

Once the payment request is accepted from your application and MGR successfully receives the 202 response code, MGR will continue waiting for the payment to complete at your end. At this stage, your application should be working to process the payment by whatever means. Once your application finishes with the payment processing, it is then required to notify MGR of the final result of the payment as described in the following section.

YOUR APPLICATION > MGR

To notify MGR, your application must make a “POST” request at this URL “https://www.mygadgetrepairs.com/external/payments/custom/notify” with the following JSON body.

{
  "payment_uuid": "35-digit-uuid-xxxx-xxx-xxx",
  "status": "APPROVED",
  "auth_code": "123xxx",
  "txn_ref": "123xxx789"
}

{payment_uuid} = Exactly the same “payment_uuid”, MGR sent to your webhook URL in initial request.

{status} = Can only be “APPROVED” or “DENIED”.

{auth_code} = Payment authorisation code in case of approval. (Not Required)

{txn_ref} = Payment transaction reference in case of approval. (Not Required)

Your request must contain the following headers:

Content-Type: application/json
X-MGR-PASSCODE: {MGR Passcode}

The header “X-MGR-PASSCODE” is only required for “Webhook” payments. You can ignore this header in notification requests for “Payment Option for Customer Portal”

NOTE: MGR can only finish the payment process successfully at its end after having a notification received from your application. During the process, the MGR payment interface must stay open with the popup displaying messages. It will be closed automatically once the notification is received from your application.

Example codes for your application to send a notification request

Simple HTTP Request

POST /external/payments/custom/notify HTTP/1.1
Host: www.mygadgetrepairs.com
Content-Type: application/json
X-MGR-PASSCODE: 123456789

{
  "payment_uuid": "35-digit-uuid-xxxx-xxx-xxx",
  "status": "APPROVED",
  "auth_code": "123abc",
  "txn_ref": "00000000"
}

cURL Request

curl --location --request POST 'https://www.mygadgetrepairs.com/external/payments/custom/notify' \
--header 'Content-Type: application/json' \
--header 'X-MGR-PASSCODE: 123456789' \
--data-raw '{
  "payment_uuid": "35-digit-uuid-xxxx-xxx-xxx",
  "status": "APPROVED",
  "auth_code": "123abc",
  "txn_ref": "00000000"
}'

PHP – cURL Request

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://www.mygadgetrepairs.com/external/payments/custom/notify",
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>"{\"payment_uuid\": \"35-digit-uuid-xxxx-xxx-xxx\", \"status\": \"APPROVED\", \"auth_code\": \"123abc\", \"txn_ref\": \"00000000\" }",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "X-MGR-PASSCODE: 13246848"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python – Requests

import requests

url = "https://www.mygadgetrepairs.com/external/payments/custom/notify"

payload = "{\"payment_uuid\": \"35-digit-uuid-xxxx-xxx-xxx\", \"status\": \"APPROVED\", \"auth_code\": \"123abc\", \"txn_ref\": \"00000000\" }"
headers = {
  'Content-Type': 'application/json',
  'X-MGR-PASSCODE': '13246848'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))