Cards & Wallets · Your payment page · Advanced features

Notifications and callbacks

Keep your back-office systems in sync by receiving notifications and callbacks when transactions finish processing.

Notifications are server-to-server messages sent after a transaction has completed. You can provide a callbacks.transactionNotification.url on each request, or set a default URL during boarding. If we cannot deliver on the first attempt, we retry. A notification is considered delivered when we receive an HTTP 200 within 10 seconds.

In-flight callbacks allow you to take actions while a transaction is still being processed, for example to approve or reject a payment before it completes. Provide callbacks.preAuthCallback.url for a callback before the transaction is sent for authorisation, and callbacks.postAuthCallback.url for one after it is authorised but before it is finalised.

Requesting notifications and callbacks

Add the URLs you want to use to a callbacks object on the payment request, each with the format you want to receive. The example below requests all three.

Payment with a notification and both in-flight callbacks
EndpointDefinition
POST /acceptor/rest/transactions/{instId}/payment
Request body
{
    "transaction": {
        "currency": "GBP",
        "amount": 25.00,
        "merchantRef": "TXN-0001",
        "description": "Sample Payment",
        "commerceType": "ECOM"
    },
    "paymentMethod": {
        "card": {
            "pan": "9900000000000010",
            "expiryDate": "1229",
            "cv2": "123",
            "cardHolderName": "John Smith"
        },
        "billingAddress": {
            "line1": "1 Some Street",
            "city": "Metropolis",
            "postcode": "AA1 2BB",
            "countryCode": "GBR"
        }
    },
    "callbacks": {
        "transactionNotification": {
            "url": "https://www.example.com/transactionNotification",
            "format": "REST_JSON"
        },
        "preAuthCallback": {
            "url": "https://www.example.com/preAuthCallback",
            "format": "REST_JSON"
        },
        "postAuthCallback": {
            "url": "https://www.example.com/postAuthCallback",
            "format": "REST_JSON"
        }
    }
}
cURL
curl -X POST "{targetEnvironmentPath}/acceptor/rest/transactions/{instId}/payment" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
        "currency": "GBP",
        "amount": 25.00,
        "merchantRef": "TXN-0001",
        "description": "Sample Payment",
        "commerceType": "ECOM"
    },
    "paymentMethod": {
        "card": {
            "pan": "9900000000000010",
            "expiryDate": "1229",
            "cv2": "123",
            "cardHolderName": "John Smith"
        },
        "billingAddress": {
            "line1": "1 Some Street",
            "city": "Metropolis",
            "postcode": "AA1 2BB",
            "countryCode": "GBR"
        }
    },
    "callbacks": {
        "transactionNotification": {
            "url": "https://www.example.com/transactionNotification",
            "format": "REST_JSON"
        },
        "preAuthCallback": {
            "url": "https://www.example.com/preAuthCallback",
            "format": "REST_JSON"
        },
        "postAuthCallback": {
            "url": "https://www.example.com/postAuthCallback",
            "format": "REST_JSON"
        }
    }
}'

Details provided on the request take precedence over any defaults set on your account.

See notifications for the message formats and retry behaviour, and in-flight call-backs for the callback request and response formats and the rules your handler must follow.