Webhooks

PEX support TLS 1.2 and higher versions. PEX does NOT support TLS 1.0 and 1.1

PEX sends 4 types of webhooks: Card Network Transaction, Card Status Change, and Card Shipment, Virtual Card.

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, you can manage webhooks by visiting Business Settings > Developer Tools on your Dashboard. From this page, you can configure the events you wish to subscribe to; PEX will then begin issuing HTTPS POST requests to your endpoints with information about the events. For additional support, contact API Support or your client success manager.

Webhook headers

POST
    Connection: Keep-Alive
    Content-Length: 761
    Content-Type: application/json; charset=utf-8
    Authorization: Basic QTM1Q0JENkE2Mzc1NDYxQThFQzE0MUZBQTk1QzI1MEY=
    X-PEX-Version: 2.0.1.1
    Expect: 100-continue
    Host: coreapi.pexcard.com
    Request-Context: appId=cid-v1:894ea26b-2fc9-45f1-ac12-e0c7d4083452
    Request-Id: |5240accf-42dfdcaf1157b7f7.

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 secret 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.

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:

All webhooks for network transaction events use the same format. For definitions of the meaning of these fields, please refer to the API Documentation for GET /Details/TransactionDetails.

Note that each type of network transaction event webhook can be subscribed to independently.

Types of Network Transactions

PEX currently provides webhooks for 5 types of network transaction events. Network transaction events are identified by "TransactionType":"NETWORK". The type of transaction can be identified by using the NetworkType and NetworkStatus fields. NetworkType can be one of four values: Auth, Pin, Settlement, Reversal. NetworkStatus can be one of two values: Approved, Declined. All Reversal events will have a default NetworkStatus value of Approved.

You can subscribe to receive each type of event on separate endpoints:

• Authorization (Signature Transactions;Type 0100)
• Reversal (Type 0420)
• Settlement (Type 0220)
• PIN Transaction (Type 0200)
• Decline (Note the decline endpoint will receive both declined (signature) Authorization Transaction decline events and PIN Transaction decline events.)

Although the Description field may contain information about the kind of transaction, this field should not be relied upon to identify the type of transaction.

Timestamp Fields

All date/time values are in EST (eastern standard time) unless otherwise noted.

• TransactionTime: The date/time when authorization request was received from the network.
• HoldTime: Date/time a hold was placed on the card account balance. HoldTime will be null for Authorizations as the hold is placed concurrently with the webhook event.
• SettlementTime: Funds have been transferred to the merchant and the transaction is final. Use this for reconciliation purposes. SettlementTime will be null for Authorizations and any transactions where "NetworkStatus":"Declined".
• MerchantLocalTime: Local time for the POS used for the transaction. The date/time is provided by the merchant and does not include time zone information. As this value is set on the POS, it may not be accurate.

Authorization (Signature Transactions; Type 0100)

{
    "CallbackTime": "2017-09-07T11:11:12.9622559-04:00",
    "Data": {
        "NetworkTransactionId": 127348106,
        "TransactionId": null,
        "AcctId": 660702,
        "TransactionTime": "2017-09-07T11:11:12",
        "HoldTime": null,
        "SettlementTime": null,
        "MerchantLocalTime": "2017-09-07T11:11:11",
        "AuthTransactionId": null,
        "TransactionAmount": 3.75,
        "PaddingAmount": 0.0,
        "AvailableBalance": 30.0,
        "LedgerBalance": 30.0,
        "TransactionType": "NETWORK",
        "Description": "Pending",
        "TransactionNotes": null,
        "ReferencedTranId": null,
        "ReferencedTransactionTime": null,
        "MerchantName": "STARBUCKS STORE 05642",
        "MerchantCity": "NORTH HOLLYWO",
        "MerchantState": "CA",
        "MerchantZip": "91601 ",
        "MerchantCountry": "US",
        "MCCCode": "5814",
        "AuthIdentityResponseCode": "274526",
        "MerchantId": "260000097015002",
        "TerminalId": "002 ",
        "NetworkType": "Auth",
        "NetworkStatus": "Approved",
        "IsCardPresent": true,
        "Message": null,
        "MessageCode":null
    }
}

When a PEX card is used to make a (signature) purchase, a merchant will request an authorization for a charge to the card and an authorization event is generated. The authorization request checks that the funds are available on the card and can be either Approved or Declined.

If the authorization is successful, the transaction amount will be placed on hold on the card for a period of time, reducing the amount available for other purchases. If the purchase is not settled ('captured') within this time, the hold is canceled and on-hold funds are released. This hold period is typically five days, but may vary by merchant.

Note that a transaction using a PIN will not generate an authorization event. See PIN Transaction for details on webhooks for PIN transactions.

Reversal (Type 0420)

{
    "CallbackTime": "2019-09-07T04:05:43.4025944-04:00",
    "Data": {
        "NetworkTransactionId":2265018,
        "TransactionId":null,
        "AcctId":7378,
        "TransactionTime":"2017-09-07T04:05:42",
        "HoldTime":null,
        "SettlementTime":null,
        "MerchantLocalTime":"2017-09-07T04:03:35",
        "AuthTransactionId":2465657071,
        "TransactionAmount":2.0,
        "PaddingAmount":0.0,
        "AvailableBalance":154.0,
        "LedgerBalance":154.0,
        "TransactionType":"NETWORK",
        "Description":"Reversal",
        "TransactionNotes":null,
        "ReferencedTranId":2465657071,
        "ReferencedTransactionTime":"2017-09-07T04:03:35",
        "MerchantName":"Merch Name",
        "MerchantCity":"Iv-Fr",
        "MerchantState":"CO",
        "MerchantZip":"760009874",
        "MerchantCountry":"US",
        "MCCCode":"5812",
        "AuthIdentityResponseCode":"529958",
        "MerchantId":"000065432112514",
        "TerminalId":"6548526 ",
        "NetworkType":"Reversal",
        "NetworkStatus":null,
        "IsCardPresent":true,
        "Message":null,
        "MessageCode":null,
        "MerchantRequestedAmount":2.0
    }
}

A merchant may decide to reverse a previous authorization and release the funds that were previously on hold for a given purchase. This will result in an increase to the available funds on the account. A merchant may also decide to reverse a PIN Transaction, in which case the funds that were debited from the account will be credited back to the account.

If available, the AuthTransactionId can be used to find the associated authorization which is being reversed. However, the id of the associated authorization may not always be available. Visa reviewed thousands of authorization reversal transactions over a three month period and found that many merchants send incomplete or incorrect information in the reversal message. This means that the issuer is not able to properly identify and remove the matching authorization hold.

Settlement (Type 0220)

{
    "CallbackTime": "2017-09-07T04:09:30.0986603-04:00", 
    "Data": {
        "NetworkTransactionId":2265018,
        "TransactionId":2465657073,
        "AcctId":7378,
        "TransactionTime":"2017-09-07T04:03:35",
        "HoldTime":"2017-09-07T04:03:35",
        "SettlementTime":"2017-09-07T04:03:54",
        "MerchantLocalTime":"2017-09-07T04:03:35",
        "AuthTransactionId":2465657071,
        "TransactionAmount":-2.0,
        "PaddingAmount":0.0,
        "AvailableBalance":154.0,
        "LedgerBalance":154.0,
        "TransactionType":"NETWORK",
        "Description":"Settlement",
        "TransactionNotes":null,
        "ReferencedTranId":2465657071,
        "ReferencedTransactionTime":"2017-09-07T04:03:35",
        "MerchantName":"Merch Name",
        "MerchantCity":"Iv-Fr",
        "MerchantState":"CO",
        "MerchantZip":"760009874",
        "MerchantCountry":"US",
        "MCCCode":"5812",
        "AuthIdentityResponseCode":"529958",
        "MerchantId":"000065432112514",
        "TerminalId":"6548526 ",
        "NetworkType":"Settlement",
        "NetworkStatus":null,
        "IsCardPresent":true,
        "Message":null,
        "MessageCode":null,
        "MerchantRequestedAmount":-2.0
    }
}

A settlement event is generated when the merchant 'captures' the funds previously authorized as part of a signature transaction. Note that NetworkStatus is null for all settlement events.

PIN Transaction (Type 0200)

{
    "CallbackTime": "2017-09-07T05:19:47.1675395-04:00",
    "Data": {
        "NetworkTransactionId":2265021,
        "TransactionId":null,
        "AcctId":7378,
        "TransactionTime":"2017-09-07T05:19:46",
        "HoldTime":null,
        "SettlementTime":null,
        "MerchantLocalTime":"2017-09-07T05:19:45",
        "AuthTransactionId":null,
        "TransactionAmount":-15.0,
        "PaddingAmount":0.0,
        "AvailableBalance":156.0,
        "LedgerBalance":156.0,
        "TransactionType":"NETWORK",
        "Description":"Settlement",
        "TransactionNotes":null,
        "ReferencedTranId":null,
        "ReferencedTransactionTime":null,
        "MerchantName":"Merch N",
        "MerchantCity":"",
        "MerchantState":"",
        "MerchantZip":"760009874",
        "MerchantCountry":"",
        "MCCCode":"5812",
        "AuthIdentityResponseCode":"394297",
        "MerchantId":"000065432112514",
        "TerminalId":"12313123",
        "NetworkType":"Pin",
        "NetworkStatus":"Approved",
        "IsCardPresent":true,
        "Message":null,
        "MessageCode":null,
        "MerchantRequestedAmount":-15.0
    }
}

When a PEX card is used for transaction that is completed with a PIN (Personal Identification Number), a PIN transaction event is generated. In a PIN transaction, funds are immediately debited from the card account. Note that the Description field will read Settlement as the funds have been debited.

Decline

{
    "CallbackTime": "2017-09-07T03:36:19.0333786-04:00",
    "Data": {
        "NetworkTransactionId":2265017,
        "TransactionId":null,
        "AcctId":7378,
        "TransactionTime":"2017-09-07T03:32:11",
        "HoldTime":null,
        "SettlementTime":null,
        "MerchantLocalTime":"2017-09-07T03:32:11",
        "AuthTransactionId":null,
        "TransactionAmount":-15.0,
        "PaddingAmount":0.0,
        "AvailableBalance":156.0,
        "LedgerBalance":156.0,
        "TransactionType":"NETWORK",
        "Description":"Declined",
        "TransactionNotes":null,
        "ReferencedTranId":null,
        "ReferencedTransactionTime":null,
        "MerchantName":"Merch N",
        "MerchantCity":"",
        "MerchantState":"",
        "MerchantZip":"760009874",
        "MerchantCountry":"",
        "MCCCode":"5812",
        "AuthIdentityResponseCode":"",
        "MerchantId":"000065432112514",
        "TerminalId":"12313123",
        "NetworkType":"Pin",
        "NetworkStatus":"Declined",
        "IsCardPresent":true,
        "Message": "Unauthorized merchant category: Hardware Stores",
        "MessageCode":"decline.rule.mcc",
        "MerchantRequestedAmount":-15.0
    }
}

PEX may determine that a transaction should not be honored, based on various criteria. For example, the transaction may not comply with the restrictions ('rules') placed on the card or sufficient funds are not available. In this situation, a decline event is generated. The decline webhook includes details about the transaction and the reason for the decline.

A declined transaction can be identified by having "NetworkStatus":"Declined"

Details about why a transaction was declined is provided in the Message field. Transaction decline reasons are categorized by a unique and self describing MessageCode identifying either a single decline reason or a category of decline reasons.

Below is a list of message codes and the corresponding messages that can be returned when a transaction is declined.

Additional information about declined transactions can be found in the Knowledge Base.

Card Status Change

{
    "CallbackTime": "2019-08-22T12:20:53.7335395+03:00",
    "Data": {
        "AcctId": 123213234,
        "TransactionType": "CARD",
        "Description": "Status Change",
        "FirstName": "Jane",
        "LastName": "Doe",
        "CustomId": "F1Q52343SF",
        "CardList":[
            {
                "CardId": 6231,
                "IssueDate": "2014-11-26T00:00:00",
                "ExpirationDate": "2017-11-30T00:00:00",
                "Last4CardNumber": "1212",
                "CardStatus": "CLOSED",
                "CardOrderId": 55233
            }
        ]
    }
}

You can subscribe to the Card Status Change webhook to receive a callback when there is a change in the status of a card. A card can be one of the following statuses: ACTIVE, BLOCKED, CLOSED or INACTIVE In most cases you will receive webhook call as soon as card status is changed, but in some cases there could be delays depending upon the processing queue.

Card Shipping Information

{
    "CallbackTime": "2019-08-22T12:20:53.7335395+03:00",
    "Data": {
        "AcctId": 11111,
        "TransactionType": "CARDORDER",
        "Description": "Shipped",
        "TrackingNumber": "9400015001052000000000",
        "ShippingMethod": "USPS",
        "Last4CardNumber": "1234",
        "CardOrderId": 1221
    }
}

You can subscribe to the Card Shipping Information webhook to receive a message when the cards you ordered are embossed and shipped. This webhook will contain the shipping provider and tracking number so you can track the shipment.

Virtual Card Sensitive Data

{
    "CallbackTime": "2019-12-27T05:35:52.4142456-05:00",
    "Data": {
        "AccountId": 12343,
        "AccountNumber": "10000000353902",
        "FirstName": "Jon",
        "LastName": "Snow",
        "CardNumber": "4111123412341234",
        "ExpirationDate": "2020-12-31T00:00:00",
        "CVV2": "123",
        "Status": "ACTIVE",
        "Balance": 400.0,
        "VirtualCardOrderId": 13232,
        "OrderDateTime": "2017-12-27T05:35:25.847",
        "Errors": [],
        "Message": "Account Creation Successful"
    }
}

The virtual card order process is asynchronous so theoretically a variety of errors could occur. Below are a few examples and how Errors and Messages would appear in the original callback

completely successful, no errors

{
    "Errors": [],
    "Message": "Account Creation Successful"
}

completely failed - card was not created

{
    "Errors": [ "Card" ],
    "Message": "Failed: Card Creation"
}

partial fail of some post card creation actions (group or ruleset or activation or funding)

{
    "Errors": [ "Group", "Ruleset", "Activation", "Funding" ],
    "Message": "Failed: Set Group, Set Ruleset, Activation, Funding"
}

You can subscribe to the Virtual Card Sensitive Data webhook to receive details your newly created virtual cards. Card data, including the 16 digit PAN and CVV2, is sensitive data. Do not store the data contained in this webhook. You can retrieve the card data at any point by using POST /VirtualCard/Data to request a resend of the webhook. Note that when using the /VirtualCard/Data endpoint, you can only request webhook data for one virtual card at a time.

Errors and Message are only present for the webhook associated with the original order (/VirtualCard/Order). In the re-sent callback message (i.e. POST/VirtualCard/Data) they are always empty. This is because, funding, activation or any other successful or failed event associated with a virtual card order can be updated manually via other API calls.

Within the Errors array are the following values:

• Card
• Group
• Ruleset
• Activation
• Funding

Endpoint Configuration

You must use TLS (1.2 or later) to secure your URLs (ie. https://)

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.

If you are ready to start using PEX webhooks, log in to your Dashboard and go to the Business Settings > Developer Tools page. The URL endpoints should adhere to the following:

• 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

Configuration notes

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)
3. PEX hosts webhook delivery relays in multiple public cloud regions and therefore cannot guarantee that webhooks will arrive from a particular IP address. You should use the Authorization header to verify the shared secret matches to ensure the webhooks originate from PEX.