NOTYD API (v1)

Download OpenAPI specification:Download

E-mail: [email protected]

Welcome to the NOTYD 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",
  • "due_date": "2021-10-22T08:19:28.258525Z",
  • "company": {
    },
  • "seller": {
    },
  • "dunning_status": {
    },
  • "value": {
    },
  • "refunds": [
    ],
  • "total_due_excl_tax_in_currency_units": 400,
  • "tax": {
    },
  • "invoice_lines": [
    ],
  • "upcoming_payment_reminder_sent": 0,
  • "upcoming_payment_reminder_sent_at": null,
  • "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,
  • "file": "https://biller-ai-django-media-files.s3.amazonaws.com/payment-request-1234.pdf",
  • "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 5 50 55 60 65 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.


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


{
  • "count": 123,
  • "next": "http://api.example.org/accounts/?page=4",
  • "previous": "http://api.example.org/accounts/?page=2",
  • "results": [
    ]
}
Mark invoice as paid to seller
This action marks invoice as paid to seller so we stop chasing the buyer.


SecurityjwtAuth 
Request 
path Parameters
uuid
required
string
Invoice UUID string identifying the invoice that should be marked as paid to seller


 
Responses 
200
404
post/v1/api/invoices/{uuid}/mark_as_paid_to_seller/
Request samples 
Response samples 
application/json
{
  • "id": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "description": "Invoice is marked as paid to seller"
}
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",
  • "due_date": "2021-10-22T08:19:28.258525Z",
  • "company": {
    },
  • "seller": {
    },
  • "dunning_status": {
    },
  • "value": {
    },
  • "refunds": [
    ],
  • "total_due_excl_tax_in_currency_units": 400,
  • "tax": {
    },
  • "invoice_lines": [
    ],
  • "upcoming_payment_reminder_sent": 0,
  • "upcoming_payment_reminder_sent_at": null,
  • "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,
  • "file": "https://biller-ai-django-media-files.s3.amazonaws.com/payment-request-1234.pdf",
  • "representative": {
    },
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "seller_company_address": {
    }
}
JWT Tokens
Create token
In order to use NOTYD 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 order request, starting the purchase flow for the buyer.


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


Please use three amounts (total_amount_incl_tax, total_amount_excl_tax, total_amount_tax)
when create an order request


SecurityjwtAuth 
Request 
Request Body schema: 
external_webshop_uid
string or null <uuid>  (Webshop ID configured by NOTYD) 
Unique identifier of the Webshop used in communications between the webshop and NOTYD.


 
external_order_uid
required
string (External order ID)   <= 255 characters 
Order identifier used by the Webshop.


 
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
string
Currency code according to ISO 4217.


 Enum: "GBP" "DKK" "EUR"  
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,
  • "seller_urls": {},
  • "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",
  • "payment_page_url": "https://api.sandbox.biller.ai/order-request/27e91c76-35fa-4f3e-9279-bee06a94e1ca",
  • "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,
  • "seller_urls": {},
  • "webhook_urls": {},
  • "amount": 59500
}
Orders
Cancel 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 NOTYD know that you have shipped the goods, and NOTYD 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",
  • "invoice_url": "http://myinvoice.com/1234/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",
  • "status": "partially_captured",
  • "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,
  • "next": "http://api.example.org/accounts/?page=4",
  • "previous": "http://api.example.org/accounts/?page=2",
  • "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
{}