Event notifications
System-generated events record changes to data within the AffiniPay Payment Gateway. You can retrieve events so your application or business system can respond accordingly when system changes occur.
You can retrieve event data:
- On demand by polling the list events endpoint (recommended)
- Automatically using webhooks
Types of events
You can retrieve information about AffiniPay Payment Gateway events that focus on the status of transactions and recurring charges on a merchant account. See Event Handling for a list of the types of events you can receive.
With webhooks you can also retrieve information about partner OAuth application events that focus on the disposition of new AffiniPay merchant applications submitted to AffiniPay as part of connecting merchants for white labeled payments.
Polling the list events endpoint
You can poll the list events endpoint to retrieve merchant application events and payment gateway events from a specified start date.
If you choose to do so:
- Schedule the polling at least monthly.
- Set a polling window that ensures that you don’t miss any data.
Retrieve the 2 most recent events
curl -X GET --user secret_key: 'https://api.affinipay.com/v1/events?page=1&page_size=2'Example response
{
"page": 1,
"page_size": 2,
"total_entries": 736,
"results": [
{
"id": "LhBgkp4oScmr3wEeyHKzZw",
"created": "2016-10-25T17:46:33.792Z",
"type": "transaction.authorized",
"data": {
"id": "AfLZQYR2RLGRqBxDo4IKIQ",
"created": "2016-10-25T17:46:33.786Z",
"modified": "2016-10-25T17:46:33.786Z",
"account_id": "8IO47jzCEeOfvhLxg70sog",
"status": "AUTHORIZED",
"amount": 100,
"currency": "USD",
"auto_capture": true,
"amount_refunded": 0,
"authorization_code": "U2QF6A",
"type": "CHARGE",
"method": {
"name": "Some Customer",
"address1": "123 Main St",
"postal_code": "78730",
"type": "card",
"number": "************4242",
"fingerprint": "GunPelYVthifNV63LEw1",
"card_type": "VISA",
"exp_month": 10,
"exp_year": 2025,
"cvv": "***"
}
}
}, {
"id": "L6vN5PwhRDG9SDKxDwghJQ",
"created": "2016-10-25T17:46:33.781Z",
"type": "transaction.created",
"data": {
"id": "AfLZQYR2RLGRqBxDo4IKIQ",
"created": "2016-10-25T17:46:33.778Z",
"modified": "2016-10-25T17:46:33.778Z",
"account_id": "8IO47jzCEeOfvhLxg70sog",
"status": "PENDING",
"amount": 100,
"currency": "USD",
"auto_capture": true,
"amount_refunded": 0,
"authorization_code": "U2QF6A",
"type": "CHARGE",
"method": {
"name": "Some Customer",
"address1": "123 Main St",
"postal_code": "78730",
"type": "card",
"number": "************4242",
"fingerprint": "GunPelYVthifNV63LEw1",
"card_type": "VISA",
"exp_month": 10,
"exp_year": 2025,
"cvv": "***"
}
}
}
]
}
Retrieve the next 5 Events starting from Oct 1, 2016 at 14:33:29.105 UTC
curl -X GET --user secret_key: 'https://api.affinipay.com/v1/events?page=1&page_size=5&start_date=2016-10-01T14:33:29.105Z'Example response
{
"page": 1,
"page_size": 5,
"total_entries": 136,
"results": [
{
"id": "RsRwETpFSJ2L3lyuPaFO0Q",
"type": "transaction.created",
"created": "2016-10-25T18:08:22.199Z",
"data": {
"id": "z2jUj9JyRNG_nIQZr9L_CA",
"created": "2016-10-25T18:08:22.148Z",
"modified": "2016-10-25T18:08:22.148Z",
"account_id": "TU0BOD2gEeOfvhLxg70sog",
"status": "PENDING",
"amount": 1256,
"currency": "USD",
"auto_capture": false,
"reference": "auth ref 1256",
"amount_refunded": 0,
"authorization_code": "ZXSKRB",
"type": "CHARGE",
"method": {
"name": "Some Customer",
"address1": "123 Main St",
"postal_code": "78730",
"type": "card",
"number": "************4242",
"fingerprint": "GunPelYVthifNV63LEw1",
"card_type": "VISA",
"exp_month": 10,
"exp_year": 2025,
"cvv": "***"
}
}
}, {
"id": "h00xvpjLS6usI3_Uv1TMlw",
"created": "2016-10-25T18:08:22.293Z",
"type": "transaction.authorized",
...
}, {
"id": "WjqzlbTwSHqB0xYS1BznXw",
"created": "2016-10-25T18:08:22.436Z",
"type": "transaction.created",
...
}, {
"id": "3mLZet76SrOMg0Gs3QsTbA",
"created": "2016-10-25T18:08:22.473Z",
"type": "transaction.authorized",
...
}, {
"id": "0QkrSnlaRW2F6GdiUd8w0Q",
"created": "2016-10-25T18:08:22.567Z",
"type": "transaction.created",
...
}
]
}
Configuring webhook URLs
Webhooks enable you to retrieve event information automatically by exposing an endpoint. If you choose to use webhooks, keep in mind that:
- The events you receive aren’t batched or sequenced.
- Anyone can send data to the URL configured for your webhook.
- Data can be lost if your system doesn’t respond with a 200 OK message before the maximum number of retries.
Configuring webhooks depends on which type of event you’re targeting.
Configuring webhooks for Payment Gateway events
You can configure AffiniPay Payment Gateway webhooks through the AffiniPay web application or the AffiniPay Payment Gateway API.
To configure AffiniPay Payment Gateway webhooks through the AffiniPay web application:
- Log in to the web application that corresponds to the product you’re integrating into your application.
- For AffiniPay: https://secure.affinipay.com/login
- For ClientPay: https://secure.clientpay.com/login
- For CPACharge: https://secure.cpacharge.com/login
- For LawPay: https://secure.lawpay.com/login
- In the web application, click your name in the top-right corner and click Developers. (This part of the web application is available only to users with the Administrator or Developer role and to the merchant owner.)
- Scroll to the Webhooks section and specify one or more URLs where you want AffiniPay to send events and press Enter or Return. You can specify different URLs for test- and live-mode transaction events. Changes that aren’t associated with either mode are sent to both sets of URLs.
- Click Save Changes.
Partner OAuth Application Events
You must configure partner OAuth application webhooks through the AffiniPay web application.
To configure partner OAuth application webhooks:
- Log in to the web application that corresponds to the product you’re integrating into your application.
- For AffiniPay: https://secure.affinipay.com/login
- For ClientPay: https://secure.clientpay.com/login
- For CPACharge: https://secure.cpacharge.com/login
- For LawPay: https://secure.lawpay.com/login
- In the web application, click your name in the top-right corner and click Developers. (This part of the web application is available only to users with the Administrator or Developer role and to the merchant owner.)
- The My Partner Applications section on the right lists your partner OAuth applications. Locate the partner OAuth application you want to configure and click Edit.
- Specify where you want AffiniPay to send events in the Event URL field.
- Click Save.