PEX can send webhook notifications to customers in response to a variety of events. An event is an activity, such as a card transaction at a point-of-sale (POS) terminal or a card status change. Webhooks provide more details about the event. For example, a notification might alert a customer that a card was used and include details regarding the outcome of the attempted transaction.
To receive webhook notifications, you will need to pre-configure and host endpoints for each of the webhooks you wish to receive. After setting up the endpoints, contact API Support or your client success manager with details of the endpoints and the events you wish to receive. PEX will then begin issuing HTTPS POST requests to your endpoints with information about the event.
PEX support TLS 1.1 and higher versions. PEX does NOT support TLS 1.0
PEX sends 3 types of webhooks: Card Network Transaction, Card Status Change, and Card Shipment.
PEX takes security and scalability seriously. To allow our customers to authenticate webhook calls, all webhooks include an authentication header.
PEX uses HTTP Basic Authentication (HTTPS) in order to securely authenticate webhooks calls. With HTTP Basic Authentication, a shared secred key is base64 encoded and passed in header. Customers can compare a decoded copy of this value against the shared secret to authenticate the webhook call.
Customers should contact API Support to receive their shared secret. Please store your shared secret in a secure location and do not share it.
HTTP POSTConnection: Keep-Alive
Content-Type: application/json; charset=utf-8
Authorization: Basic QTM1Q0JENkE2Mzc1NDYxQThFQzE0MUZBQTk1QzI1MEY=
- Card Network Transactions
Transaction events are generated when a network transaction occurs. There are several types of network transaction events. You can subscribe to receive a webhook for each type of network event independently:
- Card Status Change
This event is generated when the status of a card changes. Activating a card, blocking a card, and closing a card will all generate card status change events.
Card Shipping Information
After placing an order for new cards, a card shipping information event is generated when the card order is shipped to the cardholder.
- Virtual Card Sensitive Data
After placing an order for a virtual card(s), the sensitive card data data, such as the 16 digit card number, expiration date, and security code (CVV), are sent via a webhook.
If you are ready to start using PEX webhooks, please send your request, along with your endpoint URLs, to API Support or your client success manager. The URL endpoints should adheres to the following:
- HTTPS URL (ie. https://)
- URL endpoint for Auth Transaction Message
- URL endpoint for PIN Transaction Message
- URL endpoint for Settlement Transaction Message
- URL endpoint for Reversal Transaction Message
- URL endpoint for Card Status Change Message
- URL endpoint for Card Shipping Information Message
- URL endpoint for Virtual Card Sensitive Data Message
Note that 1. if a URL endpoint is not provided for a particular transaction type, then notifications will not be sent for that particular transaction type. 2. for the Card Status Change webhook, you will receive a webhook for each status change regardless of the method used to change the status (API, Admin web portal, Mobile)
If PEX does not receive a 200 or 201 response from you within 20 seconds after sending a webhook, retry attempts will be made 15, 30, 60 and 120 seconds later. One final retry attempt will be made 3600 seconds (1 hour) later. If PEX does not receive a reply to that last attempt, that notification will be deleted from the queue. You will be responsible for proactively retrieving missed transactions via the PEX API. In the unlikely event of a PEX outage, webhooks are stored and released immediately when we come back online.