In-flight callbacks allow your systems an opportunity to make decisions about the transaction while it is being processed. We will send a request to the specified endpoint which contains all the information we have about the transaction at that stage, and provides a list of available actions. Your callback handler can then decide which of these actions to take – such as proceeding with or aborting the transaction. A callback can be used to add extra custom fields to a transaction, and for Hosted Cashier sessions, you can instruct us to redirect the customer to a URL of your choice for additional processing before resuming the transaction.
Callbacks are made in real time, and interrupt transaction processing – your handler needs to respond promptly and correctly, as described below. If you only want to receive a request when the transaction is completed, and don’t need to interrupt the flow, then you should use a Notification.
Pre-Auth
Pre-auth callbacks are made prior to sending the transaction for authorisation, but after most other processing has taken place.
Our request will include all the transaction data we originally received, plus the results of any enrichment or additional processing. The 3D Secure outcome (if applicable) will be available, as will the results of Optimize rules. For Hosted Cashier sessions, if a custom field input was added by the skin, the value will be available at this stage.
Available actions will include aborting the transaction, as well as proceeding with it, so a pre-auth callback is a good choice for most integrations where additional decision making is needed.
Post-Auth
Post-auth callbacks are made after the transaction is authorised, and before it has been finalised.
Our request will include the same data as for a pre-auth callback, but will also include any information that can only be obtained from the authorisation process – such as CV2 and AVS check results for card transactions.
Depending upon the payment method or processing route, a post-auth callback may or may not be able to abort the transaction. If you choose to use a post-auth callback, you must ensure your handler is working properly and can cope with unexpected inputs, since it may have a significant impact if it malfunctions. If you’re not sure whether a post-auth callback is suitable for your needs, please contact us and we can give you more tailored advice.
To receive a callback, provide a callbacks entry in your request and populate details for the relevant stage, including the endpoint URL.
The host name in your callback URL must be resolvable in public DNS, and may not include pay360.com or any of its sub-domains. The effective IP address for the endpoint must be a public routable address (no local addresses; nothing reserved in RFC 1918). We support connecting to merchant endpoints on ports 80 or 8080 (for HTTP) and 443 or 8443 (for HTTPS).
If defaults for the type of callback requested are set on your account, the details provided in the transaction request will take precedence.
Below is the reference of how you can construct the callback entry in your request:
| callbacks { | |
| preAuthCallback { | Details of the callback made before the transaction is sent for authorisation. |
| format | string Possible Values: REST_JSON, REST_XML The format of the callback content. Defaults to REST_JSON. |
| url | string Mandatory The URL you want the callback to be sent to. This will override any defaults set on your account. Where a default is set and a blank URL field is specified, no callback will be sent. |
| } | |
| postAuthCallback { | Details of the callback made after the transaction is sent for authorisation. |
| format | string Possible Values: REST_JSON, REST_XML The format of the callback content. Defaults to REST_JSON. |
| url | string Mandatory The URL you want the callback to be sent to. This will override any defaults set on your account. Where a default is set and a blank URL field is specified, no callback will be sent. |
| } | |
| } | |
As noted above, your callback handler must respond promptly and correctly to our requests:
- a response is required within 30 seconds
- the response must have HTTP status 200; we do not support following redirects
- the response must be well-formed, and specify one of the actions listed in the callback request
For Hosted Cashier requests you can additionally request that the Customer be redirected to a URL of your choice whilst the transaction is in-flight thus tailoring the payment experience to your business needs.
If your handler does not respond properly or in time, we will automatically continue processing. Wherever possible, we will try to cancel the transaction, but please note that some payment methods, transaction types or processing routes are unable to cancel a transaction at this stage. A malfunctioning callback handler may result in unwanted cancellations, or unwanted complete transactions.
The Pay360 IP address space is 185.161.164.0/22, which covers 1024 addresses from 185.161.164.0 through 185.161.167.255 inclusive. Requests that we originate, including callbacks, will come from an address within this range. The exact addresses we use may vary from time to time.
Our APIs are continuously evolving. We will not take any fields away without giving advanced notice, but we may add new fields at any time. Your integration must be able to cope with the appearance of new fields.