Webhooks

A webhook is a notification sent to a URL using an HTTPS request. At Placetopay, webhooks allow external systems to receive real-time information about the status of a transaction.

Webhooks is a new feature that is intended to complement the cases covered by the Transaction Notification feature. Currently only the use case for Webhook ACH returns is covered.

Webhook for ACH returns

The webhook for ACH returns allows merchants to receive real-time notifications about returns on their site.

Purpose: Notify the merchant when an ACH return occurs.
Configuration: Configured in the Placetopay administrative panel through the operations team, providing the desired URL.
Event: HTTPS notification sent when an ACH return is generated.
Information sent: All direct session-related information.

Headers

X-Signature: [signature for authenticity validation]
Content-Type: application/json
Accept: application/json

Body

{
  "time": "2024-11-14T05:50:15-05:00",
  "type": "chargeback.created",
  "data": {
    "status": {
      "status": "APPROVED",
      "reason": "R01",
      "message": "Insufficient funds",
      "date": "2024-07-03T22:59:00-05:00"
    },
    "date": "2024-07-03T22:59:00-05:00",
    "transactionDate": "2024-07-03T22:59:00-05:00",
    "internalReference": 2,
    "reference": "9123418",
    "paymentMethod": "EBACH",
    "franchise": "ach",
    "franchiseName": "Ebus ACH",
    "issuerName": null,
    "amount": {
      "taxes": [
        {
          "kind": "valueAddedTax",
          "amount": 0,
          "base": 0
        }
      ],
      "currency": "USD",
      "total": 20000
    },
    "conversion": {
      "from": {
        "currency": "USD",
        "total": 20000
      },
      "to": {
        "currency": "USD",
        "total": 20000
      },
      "factor": 1
    },
    "authorization": "10000123",
    "receipt": null,
    "type": "CHARGEBACK",
    "refunded": false,
    "lastDigits": null,
    "provider": null,
    "discount": null,
    "processorFields": {
      "id": "b66f02ffff79b79ea9587b3cd3507a50",
      "b24": "R01"
    },
    "additional": {
      "merchantCode": "4549106521651",
      "terminalNumber": "19371021",
      "bankName": "Test Bank",
      "accountNumber": "6789"
    }
  }
}

Signature validation

To ensure the authenticity of the notification, each webhook from Placetopay includes a signature in the X-Signature header. You can validate this signature using an HMAC SHA-256 hash generated with the content of the notification body (body) and the transaction key (tranKey) of your site.

Validation in JavaScript

const crypto = require('crypto');

// Body of the request and received signature
const body = JSON.stringify(notificationBody);
const receivedSignature = headers['X-Signature'];

const tranKey = 'YOUR_SITE_TRANKEY';

// Generate the signature locally
const generatedSignature = crypto
  .createHmac('sha256', tranKey)
  .update(body)
  .digest('hex');

// Validate the signature
if (generatedSignature === receivedSignature) {
  console.log("The notification is authentic.");
} else {
  console.log("Invalid signature: the notification is not authentic.");
}

FAQs

How do I configure a webhook for my business?

Contact the operations team and provide the URL where you want to receive notifications. They will handle the configuration in the administrative system.

What events are currently covered by webhooks?

The only available event is chargeback.created, which corresponds to ACH returns.

What information does an ACH return webhook include?

It includes the event type, return status, specific reasons (such as insufficient funds), internal references, and amount details.

How do I validate the authenticity of a webhook?

Validate the signature in the X-Signature header using HMAC SHA-256 with your site's tranKey. Refer to the main documentation for examples.