Introduction

This API allows you to create, modify, and retrieve webhooks.

Webhooks enable you to receive HTTP callback notifications when specific events occur. To subscribe to an event, you must define the callback URL to which the notification is sent.

Sample oauth call to get a token for using the API:

curl --location --request POST 'https://onetrade.dev.api.pagonxt.com/oauth/token'
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer'
--data-urlencode 'scope=subscriptions.read subscriptions.create subscriptions.update subscriptions.delete executions.replay'
--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
--data-urlencode 'client_assertion=ey...uw'
--data-urlencode 'assertion=ey...-w'

Webhook types

For now we have three different webhook types, they are:

• payment-status. Changes of the status of payments.
• accounts-entries. Movements (entries) in Accounts of DR = debit record or CR = credit record
• collection-status. Universities, changes of status of collections
• recurrent-card-payments. Universities, recurrent card payments.

Subscriptions

You can have any number of subscriptions, even duplicated.

Sequence Number

For every subscription to a webhook you wil receive events with a sequence number. Starting in 1. If you like to repeat an event, you should pass the subscription id and the sequence number.

Typical steps

• Subscribe to a webhook event with POST /subscriptions
• Get your subscription id (via previous POST or issuing a GET /subscriptions)
• when you receive a webhook store the sequenceNumber for that subscription
• Replay any missing webhook using POST /executions/replay_execution

Verifying Webhooks Events

Before you respond to a webhook, you should verify that the webhook was sent from PagoNxt Trade and has not been forged or tampered with. You can verify this by calculating the digital signature. You should not process any requests with signatures that fail verification.

Each webhook request includes a x-signature-sha256 header, encoded as hex. The header value is the HMAC of the raw body of the message calculated using the SHA-256 hash algorithm and a private key in the form of .

NodeJS (TypeScript):

import {createHmac} from 'crypto';

export function verifySignature(signature: string, body: string, key: string): boolean {

  const verified = createHmac('sha256', key)
    .update(body)
    .digest('hex');

  return verified === signature;

}

Java:

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;


public class SignatureVerifier {

  public boolean verifySignature(String signature, String body, String key)
    throws NoSuchAlgorithmException, InvalidKeyException {

    SecretKeySpec spec = new SecretKeySpec(key.getBytes(), "HmacSHA256");
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(spec);
    String verified = bytesToHex(mac.doFinal(body.getBytes()));

    return signature.equals(verified);

  }

  private String bytesToHex(byte[] bytes) {

    final char[] hexArray = "0123456789abcdef".toCharArray();
    char[] hexChars = new char[bytes.length * 2];

    for (int j = 0, v; j < bytes.length; j++) {
      v = bytes[j] & 0xFF;
      hexChars[j * 2] = hexArray[v >>> 4];
      hexChars[j * 2 + 1] = hexArray[v & 0x0F];
    }

    return new String(hexChars);

  }

}