Invoice Callbacks

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": "invoice.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 Name	Description
`invoice.created`	The invoice has been created.
`invoice.updated`	The 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_paid`	The invoice is has been complete.

Example Callback URL Implementation in Flask

# https://example.com/callbacks/invoice
@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'