Payin Webhooks - Introduction to Tazapay

When a payin is associated with a Checkout OBO session, all webhook payloads include the on_behalf_of field (the entity ID) in the data object. This field is omitted when OBO is not used.

Payin Status specific events

These are the events created and triggered when the status of the payin changes.

Event	Description	Default (on/off)
payin.requires_payment_method	Triggers when the status is requires_payment_method	On
payin.requires_action	Triggers when the status is requires_action	On
payin.processing	Triggers when the status is processing	On
payin.succeeded	Triggers when the status is succeeded	On
payin.cancelled	Triggers when the payin is cancelled	Off

payin.requires_payment_method

JSON

{
  "type": "payin.requires_payment_method",
  "created_at": "2024-10-07T07:10:21.894488Z",
  "data": {
    "id": "pay_ahfafooi7fibakbfahoan",
    "object": "payin",
    "status": "requires_payment_method",
    "amount": 10000,
    "amount_paid": 0,
    "invoice_currency": "USD",
    "holding_currency": "USD",
    "confirm": false,
    "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=",
    "customer": "cus_crtqrhth90j0121gpt50",
    "customer_details": {
      "country": "SG",
      "email": "andrea@example.com",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "billing_details": {
      "address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "1st Street",
        "line2": "2nd Avenue",
        "postal_code": "43004",
        "state": "Singapore"
      },
      "label": "Home",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "shipping_details": {
      "address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "1st Street",
        "line2": "2nd Avenue",
        "postal_code": "43004",
        "state": "Singapore"
      },
      "label": "Home",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "payment_method_details": null,
    "latest_payment_attempt": "",
    "latest_payment_attempt_data": null,
    "payment_attempts": [],
    "reference_id": "order_12345",
    "transaction_description": "1 x Product",
    "transaction_documents": [],
    "transaction_data": [],
    "items": [],
    "success_url": "https://mystore.com/success_page",
    "cancel_url": "https://mystore.com/try_again",
    "webhook_url": "https://mystore.com/internal/webhook",
    "statement_descriptor": "tzp*mystore",
    "status_description": "",
    "partially_paid": false,
    "paid_in_excess": false,
    "cancelled_at": null,
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "created_at": "2024-10-07T07:10:21.894488Z"
  },
  "id": "evt_auigfiafaaaufaeoanfgohuehg",
  "object": "event"
}

payin.requires_action

JSON

{
  "type": "payin.requires_action",
  "created_at": "2024-10-07T07:11:05.123456Z",
  "data": {
    "id": "pay_ahfafooi7fibakbfahoan",
    "object": "payin",
    "status": "requires_action",
    "amount": 10000,
    "amount_paid": 0,
    "invoice_currency": "USD",
    "holding_currency": "USD",
    "confirm": true,
    "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=",
    "customer": "cus_crtqrhth90j0121gpt50",
    "customer_details": {
      "country": "SG",
      "email": "andrea@example.com",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "billing_details": {
      "address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "1st Street",
        "line2": "2nd Avenue",
        "postal_code": "43004",
        "state": "Singapore"
      },
      "label": "Home",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "shipping_details": {
      "address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "1st Street",
        "line2": "2nd Avenue",
        "postal_code": "43004",
        "state": "Singapore"
      },
      "label": "Home",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "payment_method_details": {
      "type": "card",
      "card": {
        "last4": "4242",
        "scheme": "visa",
        "funding": "credit",
        "issuing_country": "sg",
        "three_d_secure": {
          "result": "required"
        }
      }
    },
    "latest_payment_attempt": "pat_bfiuafuiafianifnao",
    "latest_payment_attempt_data": {
      "id": "pat_bfiuafuiafianifnao",
      "object": "payment_attempt",
      "payin": "pay_ahfafooi7fibakbfahoan",
      "status": "requires_action",
      "amount": 10000,
      "charge_currency": "USD",
      "payment_method_details": {
        "type": "card",
        "card": {
          "last4": "4242",
          "scheme": "visa",
          "funding": "credit",
          "issuing_country": "sg",
          "three_d_secure": {
            "result": "required"
          }
        }
      },
      "metadata": null,
      "created_at": "2024-10-07T07:11:05.123456Z"
    },
    "payment_attempts": ["pat_bfiuafuiafianifnao"],
    "reference_id": "order_12345",
    "transaction_description": "1 x Product",
    "transaction_documents": [],
    "transaction_data": [],
    "items": [],
    "success_url": "https://mystore.com/success_page",
    "cancel_url": "https://mystore.com/try_again",
    "webhook_url": "https://mystore.com/internal/webhook",
    "statement_descriptor": "tzp*mystore",
    "status_description": "",
    "partially_paid": false,
    "paid_in_excess": false,
    "cancelled_at": null,
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "created_at": "2024-10-07T07:10:21.894488Z"
  },
  "id": "evt_auigfiafaaaufaeoanfgohuehg",
  "object": "event"
}

payin.processing

JSON

{
  "type": "payin.processing",
  "created_at": "2024-10-07T07:12:33.456789Z",
  "data": {
    "id": "pay_ahfafooi7fibakbfahoan",
    "object": "payin",
    "status": "processing",
    "amount": 10000,
    "amount_paid": 0,
    "invoice_currency": "USD",
    "holding_currency": "USD",
    "confirm": true,
    "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=",
    "customer": "cus_crtqrhth90j0121gpt50",
    "customer_details": {
      "country": "SG",
      "email": "andrea@example.com",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "billing_details": {
      "address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "1st Street",
        "line2": "2nd Avenue",
        "postal_code": "43004",
        "state": "Singapore"
      },
      "label": "Home",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "shipping_details": {
      "address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "1st Street",
        "line2": "2nd Avenue",
        "postal_code": "43004",
        "state": "Singapore"
      },
      "label": "Home",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "payment_method_details": {
      "type": "card",
      "card": {
        "last4": "4242",
        "scheme": "visa",
        "funding": "credit",
        "issuing_country": "sg",
        "three_d_secure": {
          "eci": "05",
          "result": "authenticated",
          "version": "2.2.0"
        }
      }
    },
    "latest_payment_attempt": "pat_bfiuafuiafianifnao",
    "latest_payment_attempt_data": {
      "id": "pat_bfiuafuiafianifnao",
      "object": "payment_attempt",
      "payin": "pay_ahfafooi7fibakbfahoan",
      "status": "processing",
      "amount": 10000,
      "charge_currency": "USD",
      "payment_method_details": {
        "type": "card",
        "card": {
          "last4": "4242",
          "scheme": "visa",
          "funding": "credit",
          "issuing_country": "sg",
          "three_d_secure": {
            "eci": "05",
            "result": "authenticated",
            "version": "2.2.0"
          }
        }
      },
      "metadata": null,
      "created_at": "2024-10-07T07:11:05.123456Z"
    },
    "payment_attempts": ["pat_bfiuafuiafianifnao"],
    "reference_id": "order_12345",
    "transaction_description": "1 x Product",
    "transaction_documents": [],
    "transaction_data": [],
    "items": [],
    "success_url": "https://mystore.com/success_page",
    "cancel_url": "https://mystore.com/try_again",
    "webhook_url": "https://mystore.com/internal/webhook",
    "statement_descriptor": "tzp*mystore",
    "status_description": "",
    "partially_paid": false,
    "paid_in_excess": false,
    "cancelled_at": null,
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "created_at": "2024-10-07T07:10:21.894488Z"
  },
  "id": "evt_auigfiafaaaufaeoanfgohuehg",
  "object": "event"
}

payin.succeeded

JSON

{
  "type": "payin.succeeded",
  "created_at": "2024-10-07T07:13:47.789012Z",
  "data": {
    "id": "pay_ahfafooi7fibakbfahoan",
    "object": "payin",
    "status": "succeeded",
    "amount": 10000,
    "amount_paid": 10000,
    "invoice_currency": "USD",
    "holding_currency": "USD",
    "confirm": true,
    "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=",
    "customer": "cus_crtqrhth90j0121gpt50",
    "on_behalf_of": "ent_d3inm6ami8u10oqfm",
    "customer_details": {
      "country": "SG",
      "email": "andrea@example.com",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "billing_details": {
      "address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "1st Street",
        "line2": "2nd Avenue",
        "postal_code": "43004",
        "state": "Singapore"
      },
      "label": "Home",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "shipping_details": {
      "address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "1st Street",
        "line2": "2nd Avenue",
        "postal_code": "43004",
        "state": "Singapore"
      },
      "label": "Home",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "payment_method_details": {
      "type": "card",
      "card": {
        "last4": "4242",
        "scheme": "visa",
        "funding": "credit",
        "cardholder_name": "Andrea Lark",
        "issuing_country": "sg",
        "checks": {
          "cvc_check": "pass"
        },
        "three_d_secure": {
          "eci": "05",
          "result": "authenticated",
          "version": "2.2.0"
        }
      }
    },
    "latest_payment_attempt": "pat_bfiuafuiafianifnao",
    "latest_payment_attempt_data": {
      "id": "pat_bfiuafuiafianifnao",
      "object": "payment_attempt",
      "payin": "pay_ahfafooi7fibakbfahoan",
      "status": "succeeded",
      "amount": 10000,
      "charge_currency": "USD",
      "balance_transaction": "btr_d679f6dqd9ne66lsngb0",
      "refunded": false,
      "customer_details": {
        "country": "SG",
        "email": "andrea@example.com",
        "name": "Andrea Lark",
        "phone": {
          "calling_code": "65",
          "number": "87654321"
        }
      },
      "payment_method_details": {
        "type": "card",
        "card": {
          "last4": "4242",
          "scheme": "visa",
          "funding": "credit",
          "cardholder_name": "Andrea Lark",
          "issuing_country": "sg",
          "checks": {
            "cvc_check": "pass"
          },
          "three_d_secure": {
            "eci": "05",
            "result": "authenticated",
            "version": "2.2.0"
          }
        }
      },
      "fx_transaction": {
        "id": "fx_d209ek2fhufa9pkp5c4g",
        "object": "fx_transaction",
        "exchange_rate": 1.0,
        "initial": {
          "amount": 10000,
          "currency": "USD"
        },
        "final": {
          "amount": 10000,
          "currency": "USD"
        }
      },
      "reference_id": "TR000001385673188",
      "status_description": "",
      "metadata": null,
      "created_at": "2024-10-07T07:11:05.123456Z"
    },
    "payment_attempts": ["pat_bfiuafuiafianifnao"],
    "reference_id": "order_12345",
    "transaction_description": "1 x Product",
    "transaction_documents": [],
    "transaction_data": [],
    "items": [],
    "success_url": "https://mystore.com/success_page",
    "cancel_url": "https://mystore.com/try_again",
    "webhook_url": "https://mystore.com/internal/webhook",
    "statement_descriptor": "tzp*mystore",
    "status_description": "",
    "partially_paid": false,
    "paid_in_excess": false,
    "cancelled_at": null,
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "created_at": "2024-10-07T07:10:21.894488Z"
  },
  "id": "evt_auigfiafaaaufaeoanfgohuehg",
  "object": "event"
}

payin.cancelled

JSON

{
  "type": "payin.cancelled",
  "created_at": "2024-10-07T07:15:00.000000Z",
  "data": {
    "id": "pay_ahfafooi7fibakbfahoan",
    "object": "payin",
    "status": "cancelled",
    "amount": 10000,
    "amount_paid": 0,
    "invoice_currency": "USD",
    "holding_currency": "USD",
    "confirm": false,
    "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=",
    "customer": "cus_crtqrhth90j0121gpt50",
    "customer_details": {
      "country": "SG",
      "email": "andrea@example.com",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "billing_details": {
      "address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "1st Street",
        "line2": "2nd Avenue",
        "postal_code": "43004",
        "state": "Singapore"
      },
      "label": "Home",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "shipping_details": {
      "address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "1st Street",
        "line2": "2nd Avenue",
        "postal_code": "43004",
        "state": "Singapore"
      },
      "label": "Home",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "payment_method_details": null,
    "latest_payment_attempt": "",
    "latest_payment_attempt_data": null,
    "payment_attempts": [],
    "reference_id": "order_12345",
    "transaction_description": "1 x Product",
    "transaction_documents": [],
    "transaction_data": [],
    "items": [],
    "success_url": "https://mystore.com/success_page",
    "cancel_url": "https://mystore.com/try_again",
    "webhook_url": "https://mystore.com/internal/webhook",
    "statement_descriptor": "tzp*mystore",
    "status_description": "",
    "partially_paid": false,
    "paid_in_excess": false,
    "cancelled_at": "2024-10-07T07:15:00.000000Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "created_at": "2024-10-07T07:10:21.894488Z"
  },
  "id": "evt_auigfiafaaaufaeoanfgohuehg",
  "object": "event"
}

Payment_Attempt Specific Events:

These events are created and triggered when something of interest happens for a payment attempt.

Event	Description	Default (on/off)
payment_attempt.failed	When a payment_attempt fails	On
payment_attempt.succeeded	When the payment_attempt succeeds	Off
payment_attempt.reversed	When a payment_attempt is reversed	On

payment_attempt.failed

JSON

{
  "type": "payment_attempt.failed",
  "created_at": "2024-10-07T07:12:00.000000Z",
  "data": {
    "id": "pat_ahfafooi7ibakbfahoan",
    "object": "payment_attempt",
    "payin": "pay_bfiuafuiafianifnao",
    "status": "failed",
    "amount": 10000,
    "charge_currency": "USD",
    "customer": "cus_crtqrhth90j0121gpt50",
    "customer_details": {
      "country": "SG",
      "email": "andrea@example.com",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "payment_method_details": {
      "type": "card",
      "card": {
        "last4": "0002",
        "scheme": "visa",
        "funding": "credit",
        "cardholder_name": "Andrea Lark",
        "issuing_country": "sg",
        "checks": {
          "cvc_check": "fail"
        },
        "three_d_secure": {
          "eci": "07",
          "result": "failed",
          "version": "2.2.0"
        }
      }
    },
    "fx_transaction": null,
    "balance_transaction": null,
    "refunded": false,
    "reference_id": "TR000001385673188",
    "status_description": "Card declined",
    "metadata": null,
    "created_at": "2024-10-07T07:11:55.000000Z"
  },
  "id": "evt_auigfianfoangohuehg",
  "object": "event"
}

payment_attempt.succeeded

JSON

{
  "type": "payment_attempt.succeeded",
  "created_at": "2024-10-07T07:13:47.789012Z",
  "data": {
    "id": "pat_ahfafooi7ibakbfahoan",
    "object": "payment_attempt",
    "payin": "pay_bfiuafuiafianifnao",
    "status": "succeeded",
    "amount": 10000,
    "charge_currency": "USD",
    "customer": "cus_crtqrhth90j0121gpt50",
    "customer_details": {
      "country": "SG",
      "email": "andrea@example.com",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "payment_method_details": {
      "type": "card",
      "card": {
        "last4": "4242",
        "scheme": "visa",
        "funding": "credit",
        "cardholder_name": "Andrea Lark",
        "issuing_country": "sg",
        "checks": {
          "cvc_check": "pass"
        },
        "three_d_secure": {
          "eci": "05",
          "result": "authenticated",
          "version": "2.2.0"
        }
      }
    },
    "fx_transaction": {
      "id": "fx_d209ek2fhufa9pkp5c4g",
      "object": "fx_transaction",
      "exchange_rate": 1.0,
      "initial": {
        "amount": 10000,
        "currency": "USD"
      },
      "final": {
        "amount": 10000,
        "currency": "USD"
      }
    },
    "balance_transaction": "btr_d679f6dqd9ne66lsngb0",
    "refunded": false,
    "reference_id": "TR000001385673188",
    "status_description": "",
    "metadata": null,
    "created_at": "2024-10-07T07:11:05.123456Z"
  },
  "id": "evt_auigfianfoangohuehg",
  "object": "event"
}

payment_attempt.reversed

JSON

{
  "type": "payment_attempt.reversed",
  "created_at": "2024-10-07T07:14:30.000000Z",
  "data": {
    "id": "pat_ahfafooi7ibakbfahoan",
    "object": "payment_attempt",
    "payin": "pay_bfiuafuiafianifnao",
    "status": "reversed",
    "amount": 10000,
    "charge_currency": "USD",
    "customer": "cus_crtqrhth90j0121gpt50",
    "customer_details": {
      "country": "SG",
      "email": "andrea@example.com",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "payment_method_details": {
      "type": "card",
      "card": {
        "last4": "4242",
        "scheme": "visa",
        "funding": "credit",
        "cardholder_name": "Andrea Lark",
        "issuing_country": "sg",
        "checks": {
          "cvc_check": "pass"
        },
        "three_d_secure": {
          "eci": "05",
          "result": "authenticated",
          "version": "2.2.0"
        }
      }
    },
    "fx_transaction": {
      "id": "fx_d209ek2fhufa9pkp5c4g",
      "object": "fx_transaction",
      "exchange_rate": 1.0,
      "initial": {
        "amount": 10000,
        "currency": "USD"
      },
      "final": {
        "amount": 10000,
        "currency": "USD"
      }
    },
    "balance_transaction": "btr_d679f6dqd9ne66lsngb0",
    "refunded": false,
    "reference_id": "TR000001385673188",
    "status_description": "",
    "metadata": null,
    "created_at": "2024-10-07T07:11:05.123456Z"
  },
  "id": "evt_auigfianfoangohuehg",
  "object": "event"
}

Other Events:

Event	Description	Default (on/off)
payin.created	A payin is created	Off

payin.created

JSON

{
  "type": "payin.created",
  "created_at": "2024-10-07T07:10:21.894488Z",
  "data": {
    "id": "pay_ahfafooi7fibakbfahoan",
    "object": "payin",
    "status": "requires_payment_method",
    "amount": 10000,
    "amount_paid": 0,
    "invoice_currency": "USD",
    "holding_currency": "USD",
    "confirm": false,
    "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=",
    "customer": "cus_crtqrhth90j0121gpt50",
    "customer_details": {
      "country": "SG",
      "email": "andrea@example.com",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "billing_details": {
      "address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "1st Street",
        "line2": "2nd Avenue",
        "postal_code": "43004",
        "state": "Singapore"
      },
      "label": "Home",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "shipping_details": {
      "address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "1st Street",
        "line2": "2nd Avenue",
        "postal_code": "43004",
        "state": "Singapore"
      },
      "label": "Home",
      "name": "Andrea Lark",
      "phone": {
        "calling_code": "65",
        "number": "87654321"
      }
    },
    "payment_method_details": null,
    "latest_payment_attempt": "",
    "latest_payment_attempt_data": null,
    "payment_attempts": [],
    "reference_id": "order_12345",
    "transaction_description": "1 x Product",
    "transaction_documents": [],
    "transaction_data": [],
    "items": [],
    "success_url": "https://mystore.com/success_page",
    "cancel_url": "https://mystore.com/try_again",
    "webhook_url": "https://mystore.com/internal/webhook",
    "statement_descriptor": "tzp*mystore",
    "status_description": "",
    "partially_paid": false,
    "paid_in_excess": false,
    "cancelled_at": null,
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "created_at": "2024-10-07T07:10:21.894488Z"
  },
  "id": "evt_auigfiafaaaufaeoanfgohuehg",
  "object": "event"
}

​Payin Status specific events

​payin.requires_payment_method

​payin.requires_action

​payin.processing

​payin.succeeded

​payin.cancelled

​Payment_Attempt Specific Events:

​payment_attempt.failed

​payment_attempt.succeeded

​payment_attempt.reversed

​Other Events:

​payin.created

Payin Status specific events

payin.requires_payment_method

payin.requires_action

payin.processing

payin.succeeded

payin.cancelled

Payment_Attempt Specific Events:

payment_attempt.failed

payment_attempt.succeeded

payment_attempt.reversed

Other Events:

payin.created