Biller API (v1)

Download OpenAPI specification:Download

Welcome to the Biller API documentation.

Invoices

Get the Invoice

Get the full details of an invoice.

SecurityjwtAuth
Request
path Parameters
uuid
required
string

Invoice UUID string identifying the invoice to get the details of.

Responses
200
get/v1/api/invoices/{uuid}/
Request samples
Response samples
application/json

Response example

{
  • "id": "6a6ceb0a-c7f5-4456-84ef-6ddabddd75fd",
  • "uuid": "6a6ceb0a-c7f5-4456-84ef-6ddabddd75fd",
  • "external_invoice_uid": "123456",
  • "invoice_url": "http://example.com",
  • "payment_status": {
    },
  • "closed_at": null,
  • "created_at": "2021-09-22T10:19:28.258525+02:00",
  • "updated_at": "2021-09-22T10:19:28.258533+02:00",
  • "on_hold": null,
  • "on_hold_at": null,
  • "order_uuid": "ef04b0cd-28c2-4548-a33e-967f216cbcbf",
  • "expiry_date": "2021-11-21T08:19:28.258525Z",
  • "company": {
    },
  • "seller": {
    },
  • "dunning_status": {
    },
  • "value": {
    },
  • "refunds": [
    ],
  • "total_due_excl_tax_in_currency_units": 400,
  • "tax": {
    },
  • "invoice_lines": [
    ],
  • "invoice_due_sent": 0,
  • "invoice_due_sent_at": null,
  • "free_reminder_sent": 0,
  • "free_reminder_sent_at": null,
  • "reminder_1_sent": 0,
  • "reminder_1_sent_at": null,
  • "reminder_2_sent": 0,
  • "reminder_2_sent_at": null,
  • "last_notice_sent": 0,
  • "last_notice_sent_at": null,
  • "representative": {
    },
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "seller_company_address": {
    }
}

List the Invoices

List all invoices associated to the logged in seller user.

SecurityjwtAuth
Request
query Parameters
created_at_after
string <date>
created_at_before
string <date>
dunning_status
integer
Enum: 0 10 20 30 40 50 60 70
free_reminder_sent
integer
invoice_due_sent
integer
last_notice_sent
integer
on_hold
string

Filters on invoices that are on hold

order__external_order_uid
string

Filters on specified external order UID

order__seller_profile__uuid
string

Filters on specified Seller profile UUID

order__uuid
string

Filters on specified order UUID

ordering
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page.

payment_status
string
Enum: "not_paid" "paid" "paid_to_seller" "paid_to_seller_settled" "partially_paid" "refunded" "write_off_credit" "write_off_fraud"
reminder_1_sent
integer
reminder_2_sent
integer
search
string

A search term.

Responses
200
get/v1/api/invoices/
Request samples
Response samples
application/json

Response example

{
  • "count": 123,
  • "results": [
    ]
}

Update the Invoice

Set or update external (seller) invoice ID or invoice URL

SecurityjwtAuth
Request
path Parameters
uuid
required
string <uuid>
Request Body schema:
external_invoice_uid
string

Original invoice number of the Seller related to this invoice.

invoice_url
string <uri> <= 2000 characters

URL to the original invoice of the Seller. We recommend providing it when possible, this is essential to handle dispute or default.

Responses
200
404
patch/v1/api/invoices/{uuid}/
Request samples
{}
Response samples
application/json

Response example

{
  • "id": "6a6ceb0a-c7f5-4456-84ef-6ddabddd75fd",
  • "uuid": "6a6ceb0a-c7f5-4456-84ef-6ddabddd75fd",
  • "external_invoice_uid": "123456",
  • "invoice_url": "http://example.com",
  • "payment_status": {
    },
  • "closed_at": null,
  • "created_at": "2021-09-22T10:19:28.258525+02:00",
  • "updated_at": "2021-09-22T10:19:28.258533+02:00",
  • "on_hold": null,
  • "on_hold_at": null,
  • "order_uuid": "ef04b0cd-28c2-4548-a33e-967f216cbcbf",
  • "expiry_date": "2021-11-21T08:19:28.258525Z",
  • "company": {
    },
  • "seller": {
    },
  • "dunning_status": {
    },
  • "value": {
    },
  • "refunds": [
    ],
  • "total_due_excl_tax_in_currency_units": 400,
  • "tax": {
    },
  • "invoice_lines": [
    ],
  • "invoice_due_sent": 0,
  • "invoice_due_sent_at": null,
  • "free_reminder_sent": 0,
  • "free_reminder_sent_at": null,
  • "reminder_1_sent": 0,
  • "reminder_1_sent_at": null,
  • "reminder_2_sent": 0,
  • "reminder_2_sent_at": null,
  • "last_notice_sent": 0,
  • "last_notice_sent_at": null,
  • "representative": {
    },
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "seller_company_address": {
    }
}

JWT Tokens

Create token

In order to use Biller API you need a token for authorisation.
Create token request returns a token, which will expire in 2 hours.

Request
Request Body schema:
username
required
string
password
required
string
Responses
200
post/v1/api/token/
Request samples
{
  • "username": "string",
  • "password": "string"
}
Response samples
application/json
{
  • "access": "string",
  • "refresh": "string"
}

Refresh token

After obtaining a token from the Create token endpoint, the expire time of this token can be extended to 24 hours using the Refresh token endpoint.

Request
Request Body schema:
refresh
required
string
Responses
200
post/v1/api/refresh/
Request samples
{
  • "refresh": "string"
}
Response samples
application/json
{
  • "access": "string"
}

Order Requests

Create a new OrderRequest

Use it to create an OrderRequest, starting the purchase flow for the buyer.

The response contains the payment_page_url to redirect the buyer to Biller's hosted payment page (HPP), where the buyer can finalize the payment.

SecurityjwtAuth
Request
Request Body schema:
external_webshop_uid
string or null <uuid> (Webshop ID configured by Biller)

Unique identifier of the Webshop used in communications between the webshop and Biller.

external_order_uid
required
string (External order ID) <= 255 characters

Order identifier used by the Webshop.

amount
integer
Deprecated

Deprecated: Please use total_amount_incl_tax instead.
Total order amount (cents). Should be equal to sum of order lines product_price_incl_tax * quantity minus discount amount_incl_tax.

total_amount_incl_tax
integer

Total order amount including tax (cents). Should be equal to sum of order lines product_price_incl_tax * quantity minus discount amount_incl_tax.

total_amount_excl_tax
integer

Total order amount without tax (cents). Should be equal to the sum of order lines product_price_excl_tax * quantity minus discount amount_excl_tax

total_amount_tax
integer

Total order total tax amount (cents). Should be equal to total_amount_incl_tax minus total_amount_excl_tax

currency
required
string = 3 characters
required
Array of objects (order_request.OrderLine)

All purchased items.

required
object (OrderRequestBuyerCompany)

Buyer company information.
name or registration_number (or both) must be provided.

required
object (OrderRequestBuyerRepresentative)

Buyer representative information, to be used in the credit checks.

required
object (OrderRequestShippingAddress)

Order shipping address.

required
object (OrderRequestBillingAddress)

Order billing address.

locale
string (Locale identifier)

Based on IETF BCP 47 (ISO 369-1 language and optional ISO 3166-1 region), only the listed values are supported.

Enum: "en" "nl" "da" "fr" "de" "en_GB" "nl_BE" "fr_BE" "es_ES" "de_AT" "fi_FI" "pl_PL" "pt_PT"
object (Discount)
payment_link_duration
integer (Payment link duration in seconds.) [ 0 .. 4294967295 ]

Payment page link availability duration in seconds:

  • 900 - 15 minutes (default, used for webshops)
  • 86400 - 24 hours (payment link)
  • 604800 - 7 days (payment link)
Enum: 900 86400 604800
object (_SellerUrls)

Seller URLs to redirect the Buyer when purchase flow is finished.

object (_WebhookUrls)

Webhook URL to receive notifications about the payment status of an order

Responses
201
post/v1/api/order-request/
Request samples

Request payload example

{
  • "external_webshop_uid": "ffaf4252-8207-4b74-9668-933274b1bc5f",
  • "external_order_uid": "7304421653023",
  • "total_amount_incl_tax": 59500,
  • "total_amount_excl_tax": 49200,
  • "total_amount_tax": 10300,
  • "currency": "EUR",
  • "order_lines": [
    ],
  • "discount": {
    },
  • "buyer_company": {},
  • "buyer_representative": {
    },
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "locale": "en",
  • "payment_link_duration": 900,
  • "webhook_urls": {}
}
Response samples
application/json

Response example

{
  • "uuid": "27e91c76-35fa-4f3e-9279-bee06a94e1ca",
  • "created_at": "2021-08-24T14:15:22Z",
  • "updated_at": "2021-08-24T14:15:22Z",
  • "external_webshop_uid": "ffaf4252-8207-4b74-9668-933274b1bc5f",
  • "external_order_uid": "7304421653023",
  • "total_amount_incl_tax": 59500,
  • "total_amount_excl_tax": 49200,
  • "total_amount_tax": 10300,
  • "currency": "EUR",
  • "order_lines": [
    ],
  • "discount": {
    },
  • "buyer_company": {},
  • "buyer_representative": {
    },
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "locale": "en",
  • "payment_link_duration": 900,
  • "webhook_urls": {},
  • "amount": 59500
}

Orders

Cancel the Order

This endpoint cancels the order. Order can not be cancelled after it was captured. Cancelled is a terminal state, so no further actions are possible after order is cancelled

SecurityjwtAuth
Request
path Parameters
uuid
required
string

UUID string identifying the order to be cancelled.

Responses
200
404
409
post/v1/api/orders/{uuid}/cancel/
Request samples
Response samples
application/json
{
  • "id": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "description": "Order has been cancelled"
}

Capture the Order

Capture (part of) an accepted order to let Biller know that you have shipped the goods, and Biller will send a payment request to the Buyer. Only the captured parts of orders can be settled (paid out) and/or refunded.

The capture API considers the following scenarios:
1. Full (remaining) capture: amounts, discount, order_lines are not provided. The remaining parts of the order will be captured. If nothing is captured yet, the complete order including discount will be captured.
2. Partial-Capture: amounts are provided, discount and order_lines are optional, only specified amount and discount will be captured. Use this when only part of the goods are shipped.

SecurityjwtAuth
Request
path Parameters
uuid
required
string

UUID string identifying the order to be captured.

Request Body schema:
Array of objects (OrderLinePartialCapture)
external_invoice_uid
string

Original invoice number of the Seller related to this capture. If supplied, the original invoice number will be displayed on the payment request that Biller sends to the Buyer. This can also be set later, via the Update Invoice endpoint.

invoice_url
string <uri> <= 2000 characters

URL to the original invoice of the Seller. If available, please provide it here. If not available, please provide it, when possible, in the Update Invoice endpoint.

object

The discount on the order to be included in this capture.

amount
integer
Deprecated

Capturing amount (cents). Should be equal to sum of order lines product_price_incl_tax * quantity minus discount amount_incl_tax.

total_amount_incl_tax
integer

Capturing amount including tax (cents). Should be equal to sum of order lines product_price_incl_tax * quantity minus discount amount_incl_tax.

total_amount_excl_tax
integer

Capturing amount excl tax (cents). Should be equal to sum of order lines product_price_excl_tax * quantity minus discount amount_excl_tax.

total_amount_tax
integer

Capturing tax amount (cents). Should be equal to total_amount_incl_tax minus total_amount_excl_tax.

Responses
200
404
409
post/v1/api/orders/{uuid}/capture/
Request samples
{
  • "external_invoice_uid": "inv-2022-001234",
  • "order_lines": [
    ],
  • "discount": {
    },
  • "total_amount_incl_tax": 11100,
  • "total_amount_excl_tax": 10100,
  • "total_amount_tax": 1000
}
Response samples
application/json
{
  • "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "invoice_uuid": "f4a14dc7-f81e-45fc-974c-39f5bb2c4383",
  • "payment_reference": "BLR196X1AQP",
  • "details": "Order status updated to partially_captured"
}

Get the Order

Get the full details of an order.

SecurityjwtAuth
Request
path Parameters
uuid
required
string

UUID string identifying the order to get the details of.

Responses
200
404
get/v1/api/orders/{uuid}/
Request samples
Response samples
application/json

Response example

{
  • "uuid": "27e91c76-35fa-4f3e-9279-bee06a94e1ca",
  • "external_order_uid": "GAZAnEfwJXuVcsubEfK",
  • "company": {
    },
  • "seller": {
    },
  • "value": {
    },
  • "status": {
    },
  • "actions": {
    },
  • "created_at": "2022-08-17T15:45:29.610697+02:00",
  • "created_at_split": {
    },
  • "updated_at_split": {
    },
  • "total_amount_incl_tax": 45076,
  • "total_amount_excl_tax": 42035,
  • "total_amount_tax": 3041,
  • "order_lines": [
    ],
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "discount": {
    },
  • "representative": {
    },
  • "invoices": [
    ]
}

Get the Order status

Retrieve the status of an Order.

SecurityjwtAuth
Request
path Parameters
uuid
required
string

UUID string identifying the order to retrieve status from.

Responses
200
404
get/v1/api/orders/{uuid}/get_status/
Request samples
Response samples
application/json

Get order status example rejected

{
  • "status": "rejected"
}

Get the refundable Invoices of the Order

The response returns a list of Invoices where a refundable_quantity and a total_refundable_amount is shown for each invoice line.
The refundable_quantity is calculated as quantity minus the already refunded quantity.
The total_refundable_amount fields are calculated per line based on the refundable_quantity field and the product_price fields, being product_price the price per unit

SecurityjwtAuth
Request
path Parameters
uuid
required
string <uuid>

A UUID string identifying this order and order request.

Responses
200
404
409
get/v1/api/orders/{uuid}/refundable_invoices/
Request samples
Response samples
application/json
{
  • "count": 0,
  • "next": "string",
  • "previous": "string",
  • "results": [
    ]
}

List the Orders

List all the orders associated to the authenticated user.

SecurityjwtAuth
Request
query Parameters
created_at_after
string

Filter on created_at on or after this date. Date format: YYYY-MM-DD

created_at_before
string

Filter on created_at on or before this date. Date format: YYYY-MM-DD

dunning
string

Filters on specified dunning length

Enum: "14_days" "30_days" "60_days"
external_order_uid
string

Filters on specified external order UID

ordering
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page.

search
string

A search term.

status
string

Filters on specified order status

Enum: "accepted" "cancelled" "captured" "failed" "partially_captured" "partially_refunded" "pending" "refunded" "rejected"
Responses
200
get/v1/api/orders/
Request samples
Response samples
application/json

Response example

{
  • "count": 123,
  • "results": {
    }
}

Order captured status

Get details of what has been captured and what remains to be captured in an order

SecurityjwtAuth
Request
path Parameters
uuid
required
string

UUID string identifying the order to be queried.

Responses
200
404
get/v1/api/orders/{uuid}/capture_status/
Request samples
Response samples
application/json
{
  • "uuid": "string",
  • "order_amount": 0,
  • "uncaptured": {
    },
  • "captured": {
    }
}

Refund the Order

For full refunds, simply supply the order amount and the refund description. For partial refunds, the payload should contain only one invoice in the invoices array to be refunded. Regardless of refund method used, upon a successful refund, one credit note will be created per affected invoice.

SecurityjwtAuth
Request
path Parameters
uuid
required
string

UUID string identifying the order to be refunded.

Request Body schema:
amount
integer >= 0
Deprecated

Deprecated: Please use total_amount_incl_tax instead.
Total amount to be refunded (cents).

total_amount_incl_tax
integer

Total amount to be refunded including tax (cents).

total_amount_excl_tax
integer

Total amount to be refunded without tax (cents).

total_amount_tax
integer

Total tax amount to be refunded (cents).

description
required
string <= 255 characters

Description to be shown in the credit note, for example: "Damaged goods".

external_refund_uid
string

Refund identifier used by the Webshop, to be displayed on the credit note(s). If provided and there are multiple invoices to refund, all resulting credit notes will display the same identifier. To use different identifiers per credit note, use the field with same name within the invoices list.

Array of objects (InvoicePayload)

Please provide only one invoice at a time

Responses
200

Regardless of the refund method used, the 200 response (and the credit notes created) will have the same structure. Each entry in the refunds list represents a credit note.

404
409
post/v1/api/orders/{uuid}/refund/
Request samples
{
  • "total_amount_incl_tax": 5050,
  • "total_amount_excl_tax": 4200,
  • "total_amount_tax": 850,
  • "description": "Refund",
  • "invoices": [
    ]
}
Response samples
application/json
{
  • "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "refunds": [
    ],
  • "details": "Order status updated to partially_refunded."
}

Update the Order

Update order details.

SecurityjwtAuth
Request
path Parameters
uuid
required
string

UUID string identifying the order to be updated.

Request Body schema:
total_amount_incl_tax
integer

Capturing amount including tax (cents). Should be equal to sum of order lines product_price_incl_tax * quantity minus discount amount_incl_tax.

total_amount_excl_tax
integer

Capturing amount excl tax (cents). Should be equal to sum of order lines product_price_excl_tax * quantity minus discount amount_excl_tax.

total_amount_tax
integer

Capturing tax amount (cents). Should be equal to total_amount_incl_tax minus total_amount_excl_tax.

Array of objects (order_request.OrderLine)

All purchased items.

object (Discount)
Responses
200
404
409
patch/v1/api/orders/{uuid}/
Request samples
{
  • "total_amount_incl_tax": 0,
  • "total_amount_excl_tax": 0,
  • "total_amount_tax": 0,
  • "order_lines": [
    ],
  • "discount": {
    }
}
Response samples
application/json
{
  • "id": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "description": "Order has been patched"
}

Seller Users

Get the Seller User

Get the details for a specific seller user by UUID.

SecurityjwtAuth
Request
path Parameters
uuid
required
string <uuid>
Responses
200
get/v1/api/users/{uuid}/
Request samples
Response samples
application/json
{
  • "id": "string",
  • "uuid": "string",
  • "email": "string",
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "name": "string",
  • "is_active": true,
  • "seller_profile_uuid": "string",
  • "webshop_url": "string"
}

List the Seller Users

List all the users that belong to the same seller account as the logged in user.

SecurityjwtAuth
Request
query Parameters
page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page.

search
string

A search term.

seller_profile__seller__uuid
string <uuid>
seller_profile__uuid
string <uuid>
user__is_active
boolean
Responses
200
get/v1/api/users/
Request samples
Response samples
application/json
{}