Biftpaydocs
Dashboard

Webhooks

List webhook endpoints for the current mode

get/v1/webhook_endpoints

bash
curl https://sandbox.api.biftpay.com/v1/webhook_endpoints \
  -H "Authorization: Bearer bp_test_..."

Responses

  • 200
    Webhook endpointsobject
    Fields
    object"list"required
    dataarray of WebhookEndpointrequired
    Fields of data
    idstring (uuid)required
    object"webhook_endpoint"required
    livemodebooleanrequired
    urlstring (uri)required
    eventsarray of payment_intent.successful | payment_intent.failed | payment_intent.abandoned | payment_intent.canceled | refund.succeeded | refund.failed | payout.paid | payout.failed | payout.canceled | dispute.created | dispute.won | dispute.lost | invoice.paid | crypto_payout.paid | crypto_payout.failedrequired
    statusenabled | disabledrequired
    created_atstring (date-time)required
    has_morebooleanrequired

Register a webhook endpoint

post/v1/webhook_endpoints

The signing secret is returned once, here. URLs must be https with a public hostname. Each delivery has headers Biftpay-Event-Id, Biftpay-Timestamp and Biftpay-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<event id>.<body>">. Recompute it with the secret, compare in constant time and reject anything older than 5 minutes. Failed deliveries retry after 1m, 5m, 30m, 2h, 6h and 12h.

Parameters

Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

Body

urlstring (uri)required
eventsarray of payment_intent.successful | payment_intent.failed | payment_intent.abandoned | payment_intent.canceled | refund.succeeded | refund.failed | payout.paid | payout.failed | payout.canceled | dispute.created | dispute.won | dispute.lost | invoice.paid | crypto_payout.paid | crypto_payout.failed

Omit or leave empty for every event type.

bash
curl -X POST https://sandbox.api.biftpay.com/v1/webhook_endpoints \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://merchant.example.com/biftpay/webhooks"
  }'

Responses

  • 201
    Createdobject
    Fields
    idstring (uuid)required
    object"webhook_endpoint"required
    livemodebooleanrequired
    urlstring (uri)required
    eventsarray of payment_intent.successful | payment_intent.failed | payment_intent.abandoned | payment_intent.canceled | refund.succeeded | refund.failed | payout.paid | payout.failed | payout.canceled | dispute.created | dispute.won | dispute.lost | invoice.paid | crypto_payout.paid | crypto_payout.failedrequired
    statusenabled | disabledrequired
    created_atstring (date-time)required
    secretstringrequired
  • 400
    Invalid request

Stop sending to an endpoint

post/v1/webhook_endpoints/{id}/disable

Parameters

idstring (uuid)in pathrequired
Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

bash
curl -X POST https://sandbox.api.biftpay.com/v1/webhook_endpoints/{id}/disable \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Responses

  • 200
    The disabled endpointWebhookEndpoint
    Fields
    idstring (uuid)required
    object"webhook_endpoint"required
    livemodebooleanrequired
    urlstring (uri)required
    eventsarray of payment_intent.successful | payment_intent.failed | payment_intent.abandoned | payment_intent.canceled | refund.succeeded | refund.failed | payout.paid | payout.failed | payout.canceled | dispute.created | dispute.won | dispute.lost | invoice.paid | crypto_payout.paid | crypto_payout.failedrequired
    statusenabled | disabledrequired
    created_atstring (date-time)required
  • 404
    Not found, or not visible to this key

Start sending to a disabled endpoint again

post/v1/webhook_endpoints/{id}/enable

New events go to it from now. Send ones it missed with POST /v1/events/{id}/redeliver.

Parameters

idstring (uuid)in pathrequired
Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

bash
curl -X POST https://sandbox.api.biftpay.com/v1/webhook_endpoints/{id}/enable \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Responses

  • 200
    The enabled endpointWebhookEndpoint
    Fields
    idstring (uuid)required
    object"webhook_endpoint"required
    livemodebooleanrequired
    urlstring (uri)required
    eventsarray of payment_intent.successful | payment_intent.failed | payment_intent.abandoned | payment_intent.canceled | refund.succeeded | refund.failed | payout.paid | payout.failed | payout.canceled | dispute.created | dispute.won | dispute.lost | invoice.paid | crypto_payout.paid | crypto_payout.failedrequired
    statusenabled | disabledrequired
    created_atstring (date-time)required
  • 400
    Invalid request
  • 404
    Not found, or not visible to this key

Delete an endpoint

post/v1/webhook_endpoints/{id}/delete

Nothing more is sent to it, including deliveries still waiting, and it leaves the list. Its past deliveries stay in the event history. This can't be undone; add the URL again to get a new endpoint (with a new signing secret).

Parameters

idstring (uuid)in pathrequired
Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

bash
curl -X POST https://sandbox.api.biftpay.com/v1/webhook_endpoints/{id}/delete \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Responses

  • 200
    Deletedobject
    Fields
    idstringrequired
    object"webhook_endpoint"required
    deletedtruerequired
  • 404
    Not found, or not visible to this key

List events and their delivery status

get/v1/events

Parameters

limitintegerin query

1 to 100 · default 20

starting_afterstring (uuid)in query

The id of the last item on the previous page.

typepayment_intent.successful | payment_intent.failed | payment_intent.abandoned | payment_intent.canceled | refund.succeeded | refund.failed | payout.paid | payout.failed | payout.canceled | dispute.created | dispute.won | dispute.lost | invoice.paid | crypto_payout.paid | crypto_payout.failedin query
bash
curl https://sandbox.api.biftpay.com/v1/events \
  -H "Authorization: Bearer bp_test_..."

Responses

  • 200
    A page of eventsEventList
    Fields
    object"list"required
    dataarray of Eventrequired
    Fields of data
    idstring (uuid)required
    object"event"required
    typepayment_intent.successful | payment_intent.failed | payment_intent.abandoned | payment_intent.canceled | refund.succeeded | refund.failed | payout.paid | payout.failed | payout.canceled | dispute.created | dispute.won | dispute.lost | invoice.paid | crypto_payout.paid | crypto_payout.failedrequired
    livemodebooleanrequired
    created_atstring (date-time)required
    dataobjectrequired
    Fields of data
    objectobjectrequired

    The payment, payout or refund as it was at that moment.

    deliveriesarray of object
    Fields of deliveries
    endpoint_idstring (uuid)
    statuspending | delivered | retrying | failed
    attemptsinteger
    last_response_statusinteger | null
    has_morebooleanrequired

Send an event again to its endpoints

post/v1/events/{id}/redeliver

Parameters

idstring (uuid)in pathrequired
Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

bash
curl -X POST https://sandbox.api.biftpay.com/v1/events/{id}/redeliver \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Responses

  • 200
    How many deliveries were queuedobject
    Fields
    object"event_redelivery"
    event_idstring
    queuedinteger