Postbacks

Verify Webhooks

You are able to verify that a webhook has been received from an authorised source. All webhooks you receive will have 2 additional headers, signature and application-key.

Obtaining the secret

You can go into the API Settings on the Payment Profile, and you will be able to see a "Callback secret", if you want to generate a new webhook secret, you can click the refresh icon.

Verifying the signature

$computedSignature = hash_hmac('sha256', file_get_contents('php://input'), $configuredSigningSecret);

Card Payment Started

{
    "act": "card_payment_started",
    "status": "PENDING",
    "options": "This is the options string",
    "payment_id": 87,
    "environment": "SANDBOX",
    "payment_uuid": "992ffc9f-5fe6-4078-adbf-9cd3a3e9e9ae",
    "reference_id": "123456",
    "payment_request_id": 530,
    "payment_request_uuid": "11b8f744-6b51-4ce6-911b-80b161b05c18"
}

Card Payment Completed

{
    "act": "card_payment_completed",
    "payor": {
        "name": "Test Customer",
        "address": "Unit 5 Pickwick Walk 120 Uxbridge Road Hatch End Middlesex",
        "postcode": "HA6 7HJ"
    },
    "token": null,
    "status": "COMPLETED",
    "options": "This is the options string",
    "response": {
        "code": "0",
        "message": "AUTHCODE:724867"
    },
    "acquirer_response": {
        "code": "00",
        "message": ""
    },
    "payment_id": 87,
    "environment": "SANDBOX",
    "payment_uuid": "992ffc9f-5fe6-4078-adbf-9cd3a3e9e9ae",
    "reference_id": "123456",
    "three_d_secure_info": {
        "3d_secure_enabled": "Y",
        "3d_secure_challenge_type": "CHALLENGE_REQUESTED_MANDATE"
    },
    "transaction_id": "240429019",
    "acquirer_transaction_id": "18f9713b-90c1-43ec-8441-ac936c0b2d17",
    "payment_request_id": 530,
    "payment_request_uuid": "11b8f744-6b51-4ce6-911b-80b161b05c18"
    }

Card Payment Failed

{
    "act": "card_payment_failed",
    "status": "FAILED",
    "options": "This is the options string",
    "response": {
        "code": "66314",
        "message": "Invalid cardNumber"
    },
    "acquirer_response": {
        "code": "00",
        "message": ""
    },
    "payment_id": 88,
    "environment": null,
    "payment_uuid": "9931eaa0-a35b-446d-8622-338676bdaf05",
    "reference_id": "123456",
    "payment_request_id": 533,
    "payment_request_uuid": "3b9b3d45-b6f9-44e6-a863-8ce8a3627865",
    "transaction_id": "240429019",
    "acquirer_transaction_id": "18f9713b-90c1-43ec-8441-ac936c0b2d17",
}

Card Payment Updated

{
    "act": "card_payment_updated",
    "status": "CONFIRMED",
    "options": "This is the options string",
    "payment_id": 87,
    "environment": "SANDBOX",
    "payment_uuid": "992ffc9f-5fe6-4078-adbf-9cd3a3e9e9ae",
    "reference_id": "123456",
    "payment_request_id": 530,
    "payment_request_uuid": "11b8f744-6b51-4ce6-911b-80b161b05c18"
}

Card Payment Verified

{
    "act": "card_payment_verified",
    "payor": {
        "name": "John Smith",
        "address": "23 Rosterton Mansions 4578 Ermine Street",
        "postcode": "WD54 8TH"
    },
    "token": "9b7fd274-1dc5-4814-be12-3753bfd93a2a",
    "status": "VERIFIED",
    "options": null,
    "response": {
        "code": "0",
        "message": "ACCOUNT VALID"
    },
    "payment_id": 183,
    "environment": "SANDBOX",
    "payment_uuid": "9b7fd255-7ee8-431d-9f7e-d24725e8655a",
    "reference_id": "CARD_SETUP_3CKGU3",
    "transaction_id": "284843093",
    "acquirer_response": {
        "code": "0",
        "message": "AUTHCODE:057434"
    },
    "payment_request_id": 806,
    "three_d_secure_info": {
        "3d_secure_enabled": "Y",
        "3d_secure_challenge_type": "CHALLENGE_REQUESTED_MANDATE"
    },
    "payment_request_uuid": "77674856-2796-4700-9f10-e02023072d64",
    "acquirer_transaction_id": "65e8744ae1b75"
}

Card Payment User Cancelled

{
    "act": "card_payment_user_cancelled",
    "reason": "cancelled by user",
    "options": "This is the options string",
    "reference_id": "123456",
    "payment_request_id": 555,
    "payment_request_uuid": "549b044e-d8ca-4425-b03e-9cb6d038ff53"
}

Refund/Cancel Postbacks

Card Payment Cancelled

{
    "act": "card_payment_cancelled",
    "status": "CANCELLED",
    "options": "This is the options string",
    "response": {
        "code": "0",
        "message": "Transaction cancelled."
    },
    "payment_id": 90,
    "environment": "SANDBOX",
    "payment_uuid": "9931eba6-d286-4bc0-a936-c9c267b128a2",
    "reference_id": "123456",
    "payment_request_id": 534,
    "payment_request_uuid": "f8cfd771-d835-477d-bf36-e016ac8aed8e"
}

Card Refund Started

{
    "act": "card_refund_started",
    "status": "COMPLETED",
    "options": "This is the options string",
    "environment": "SANDBOX",
    "reference_id": "123456",
    "refund_payment_id": 89,
    "original_payment_id": 87,
    "refund_payment_uuid": "9931eb1f-c1fe-4d9a-b5b1-f6bf42645988",
    "original_payment_uuid": "992ffc9f-5fe6-4078-adbf-9cd3a3e9e9ae"
}

Card Refund Completed

{
    "act": "card_refund_completed",
    "payor": {
        "name": "Test Customer",
        "address": "Unit 5 Pickwick Walk 120 Uxbridge Road Hatch End Middlesex",
        "postcode": "HA6 7HJ"
    },
    "status": "COMPLETED",
    "options": "This is the options string",
    "response": {
        "code": "0",
        "message": "REFUND ACCEPTED"
    },
    "environment": "SANDBOX",
    "reference_id": "123456",
    "transaction_id": "240429019",
    "refund_payment_id": 89,
    "original_payment_id": 87,
    "refund_payment_uuid": "9931eb1f-c1fe-4d9a-b5b1-f6bf42645988",
    "original_payment_uuid": "992ffc9f-5fe6-4078-adbf-9cd3a3e9e9ae"
}

Card Refund Failed

{
    "act": "card_refund_failed",
    "status": "FAILED",
    "options": "This is the options string",
    "response": {
        "code": "0",
        "message": "REFUND FAILED"
    },
    "environment": "SANDBOX",
    "reference_id": "123456",
    "refund_payment_id": 89,
    "original_payment_id": 87,
    "refund_payment_uuid": "9931eb1f-c1fe-4d9a-b5b1-f6bf42645988",
    "original_payment_uuid": "992ffc9f-5fe6-4078-adbf-9cd3a3e9e9ae"
}

Card Refund Updated

{
    "act": "card_refund_updated",
    "status": "COMPLETED",
    "options": "This is the options string",
    "response": {
        "code": "0",
        "message": "REFUND ACCEPTED"
    },
    "environment": "SANDBOX",
    "reference_id": "123456",
    "refund_payment_id": 89,
    "original_payment_id": 87,
    "refund_payment_uuid": "9931eb1f-c1fe-4d9a-b5b1-f6bf42645988",
    "original_payment_uuid": "992ffc9f-5fe6-4078-adbf-9cd3a3e9e9ae"
}

Card Payment Request Forbidden

This postback will be sent when a payment request breaches a restriction limit set on the payment profile, such as:

  • Transaction limit.
  • Card has been banned.
  • IP address has been banned.
{
    "act": "card_payment_request_forbidden",
    "options": "This is the options string",
    "reference_id": "123456",
    "payment_request_id": 614,
    "restriction_details": {
        "type": "TRANSACTION_COUNT_LIMIT",
        "details": "Limit: 3, Transactions Count: 7"
    },
    "payment_request_uuid": "4c363dcf-86b8-4776-8ac6-56ab6fc7237c"
}

Card Payment Awaiting Capture

{
    "act": "card_payment_awaiting_capture",
    "status": "APPROVED",
    "options": "This is the options string",
    "payment_id": 222,
    "environment": "SANDBOX",
    "payment_uuid": "9c46a35b-81e4-4f5c-905e-be732950f87f",
    "reference_id": "TM-123456",
    "payment_request_id": 865,
    "payment_request_uuid": "084a143e-30ce-43a7-bbbf-67d1642db56e"
}