Biftpaydocs
Dashboard

Invoices

List invoices

get/v1/invoices

Parameters

statusdraft | open | paid | voidin query
customerstring (uuid)in query

Only this customer's

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

Responses

  • 200
    Invoicesobject
    Fields
    object"list"required
    dataarray of Invoicerequired
    Fields of data
    idstring (uuid)required
    object"invoice"required
    livemodebooleanrequired
    numberstringrequired
    customerstring (uuid)required
    brandstring (uuid) | null
    statusdraft | open | paid | voidrequired
    currencyNGN | USDrequired
    itemsarray of objectrequired
    Fields of items
    descriptionstringrequired
    quantityintegerrequired
    unit_amountintegerrequired
    amountintegerrequired
    totalintegerrequired

    Minor units (kobo, cents).

    at least 0

    due_datestring (date) | null
    memostring | null
    payment_intentstring (uuid) | null
    hosted_invoice_urlstring

    The customer's pay link. Present while the invoice is open (from finalize onwards, on every read); gone once paid or void.

    created_atstring (date-time)required
    finalized_atstring (date-time) | null
    paid_atstring (date-time) | null
    voided_atstring (date-time) | null
    has_moreboolean

Create a draft invoice

post/v1/invoices

Parameters

Idempotency-Keystringin headerrequired

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

up to 255 characters

Body

customerstring (uuid)required
currencyNGN | USD
brandstring (uuid)
itemsarray of objectrequired
Fields of items
descriptionstringrequired

up to 200 characters

quantityintegerrequired

at least 1

unit_amountintegerrequired

at least 1

due_datestring (date)
memostring

up to 1000 characters

bash
curl -X POST https://sandbox.api.biftpay.com/v1/invoices \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "…",
    "items": [
      {
        "description": "…",
        "quantity": 1,
        "unit_amount": 1
      }
    ]
  }'

Responses

  • 201
    CreatedInvoice
    Fields
    idstring (uuid)required
    object"invoice"required
    livemodebooleanrequired
    numberstringrequired
    customerstring (uuid)required
    brandstring (uuid) | null
    statusdraft | open | paid | voidrequired
    currencyNGN | USDrequired
    itemsarray of objectrequired
    Fields of items
    descriptionstringrequired
    quantityintegerrequired
    unit_amountintegerrequired
    amountintegerrequired
    totalintegerrequired

    Minor units (kobo, cents).

    at least 0

    due_datestring (date) | null
    memostring | null
    payment_intentstring (uuid) | null
    hosted_invoice_urlstring

    The customer's pay link. Present while the invoice is open (from finalize onwards, on every read); gone once paid or void.

    created_atstring (date-time)required
    finalized_atstring (date-time) | null
    paid_atstring (date-time) | null
    voided_atstring (date-time) | null
  • 400
    Invalid request

Retrieve an invoice

get/v1/invoices/{id}

Parameters

idstring (uuid)in pathrequired
bash
curl https://sandbox.api.biftpay.com/v1/invoices/{id} \
  -H "Authorization: Bearer bp_test_..."

Responses

  • 200
    The invoiceInvoice
    Fields
    idstring (uuid)required
    object"invoice"required
    livemodebooleanrequired
    numberstringrequired
    customerstring (uuid)required
    brandstring (uuid) | null
    statusdraft | open | paid | voidrequired
    currencyNGN | USDrequired
    itemsarray of objectrequired
    Fields of items
    descriptionstringrequired
    quantityintegerrequired
    unit_amountintegerrequired
    amountintegerrequired
    totalintegerrequired

    Minor units (kobo, cents).

    at least 0

    due_datestring (date) | null
    memostring | null
    payment_intentstring (uuid) | null
    hosted_invoice_urlstring

    The customer's pay link. Present while the invoice is open (from finalize onwards, on every read); gone once paid or void.

    created_atstring (date-time)required
    finalized_atstring (date-time) | null
    paid_atstring (date-time) | null
    voided_atstring (date-time) | null
  • 404
    Not found, or not visible to this key

Finalize, create its payment and email the customer the checkout link

post/v1/invoices/{id}/finalize

Returns hosted_invoice_url. The invoice becomes paid when that payment succeeds (invoice.paid event).

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/invoices/{id}/finalize \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Responses

  • 200
    The open invoiceInvoice
    Fields
    idstring (uuid)required
    object"invoice"required
    livemodebooleanrequired
    numberstringrequired
    customerstring (uuid)required
    brandstring (uuid) | null
    statusdraft | open | paid | voidrequired
    currencyNGN | USDrequired
    itemsarray of objectrequired
    Fields of items
    descriptionstringrequired
    quantityintegerrequired
    unit_amountintegerrequired
    amountintegerrequired
    totalintegerrequired

    Minor units (kobo, cents).

    at least 0

    due_datestring (date) | null
    memostring | null
    payment_intentstring (uuid) | null
    hosted_invoice_urlstring

    The customer's pay link. Present while the invoice is open (from finalize onwards, on every read); gone once paid or void.

    created_atstring (date-time)required
    finalized_atstring (date-time) | null
    paid_atstring (date-time) | null
    voided_atstring (date-time) | null
  • 409
    The object is in a state that doesn't allow this

Void an unpaid invoice

post/v1/invoices/{id}/void

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/invoices/{id}/void \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Responses

  • 200
    The void invoiceInvoice
    Fields
    idstring (uuid)required
    object"invoice"required
    livemodebooleanrequired
    numberstringrequired
    customerstring (uuid)required
    brandstring (uuid) | null
    statusdraft | open | paid | voidrequired
    currencyNGN | USDrequired
    itemsarray of objectrequired
    Fields of items
    descriptionstringrequired
    quantityintegerrequired
    unit_amountintegerrequired
    amountintegerrequired
    totalintegerrequired

    Minor units (kobo, cents).

    at least 0

    due_datestring (date) | null
    memostring | null
    payment_intentstring (uuid) | null
    hosted_invoice_urlstring

    The customer's pay link. Present while the invoice is open (from finalize onwards, on every read); gone once paid or void.

    created_atstring (date-time)required
    finalized_atstring (date-time) | null
    paid_atstring (date-time) | null
    voided_atstring (date-time) | null
  • 409
    The object is in a state that doesn't allow this