Describes callbacks from invoice events

Certain events may happen during a lifespan of an invoice. For example, when an invoice gets fully paid, an event invoice.fully_paid is triggered. Merchants may choose to consume these events by providing a callback_url, so that they can act on the events if needed.

Events are delivered to callbacks via a POST request, with the authorization header of Authorization: Token MERCHANT_API_TOKEN

Event payloads follow this convention:

  "event": {
    "name": "",
    "data": {
        "id": "invoice_id",
        "currency": "PHP",
        "amount": "100",
        "amount_received": "0",
        "external_transaction_id": "1"

Events which may be consumed by callbacks are described at the following table:

Event NameDescription
invoice.createdThe invoice has been created.
invoice.updatedThe invoice has been updated. This can happen due to the invoice receiving payment or due to expiration of guaranteed rate for Bitcoin payments.
invoice.fully_paidThe invoice is has been complete.

Example Callback URL Implementation in Flask

@app.route('/callbacks/invoice', methods=['POST'])
def invoice_callback():
    body = request.get_json()
    event = data['event']
    event_name = event['name']
    data = event['data']
    # Do something based on the event name
    if event_name == 'invoice.fully_paid':
        # Process paid transaction
    elif event_name == 'invoice.created':
        # Update invoice status
    elif event_name == 'invoice.updated':
        # Update invoice status

    return 'OK'