Create an invoice

POST https://api.leapa.co/v2/invoices

This endpoint needs your API key

Send it as a bearer token in the Authorization header. A request without one is answered with 401. See Authentication for where to find your key and how to keep it secret.

Request

curl -X POST "https://api.leapa.co/v2/invoices" \
  -H "Authorization: Bearer $LEAPA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Room 204, two nights",
    "affiliate": "dwelinn",
    "sendForManualPayment": false,
    "customer_id": "cus_3d8e51fa20",
    "products": [
      {
        "quantity": 1,
        "product_id": "prd_84c2e7f019",
        "rate_ids": []
      }
    ],
    "due_date": "2026-01-31",
    "source_id": "src_0e7b3c95af",
    "manual_payment": false,
    "rate_id": "rat_20b6df3c9e",
    "amount_to_paid": 45000,
    "custom_fields": {
      "obr_code": "ADB_REGISTRE_COMMERCE"
    }
  }'

Response

Created

{
  "id": "obj_5f21c8a40b",
  "object": "string",
  "customer": {
    "id": "obj_5f21c8a40b",
    "object": "string",
    "email": "jeanne@example.com",
    "address": {
      "object": "string",
      "city": "string",
      "type": "personal",
      "status": "invalid",
      "state": "string",
      "zip": "string",
      "line1": "string",
      "line2": "string"
    },
    "status": "active",
    "first_name": "Jeanne",
    "last_name": "Ndayishimiye",
    "birth_date": "2026-01-31",
    "phone_number": "+25779123456",
    "merchant_name": "Jeanne Ndayishimiye",
    "merchant_id": "mer_1b47d0e9ca",
    "sources": [
      {
        "fingerprint": null,
        "currency": null,
        "type": null,
        "account_id": null,
        "default": null
      }
    ],
    "destinations": [
      {
        "currency": null,
        "type": null,
        "account_id": null,
        "default_destination": null
      }
    ],
    "live": false,
    "reference_id": "ref_9f2a17c4"
  },
  "currency": "BIF",
  "description": "Room 204, two nights",
  "sendForManualPayment": false,
  "automatic": false,
  "pdfLink": "string",
  "number": "string",
  "products": [
    {
      "object": "string",
      "product": {
        "id": null,
        "name": null,
        "code": null,
        "description": null,
        "status": null,
        "type": null,
        "images": null,
        "attributes": null,
        "rateId": null,
        "created_date": null,
        "price_details": null,
        "live": null,
        "rate_ids": null
      },
      "quantity": 1,
      "price": 0,
      "rate_ids": [],
      "discounted_price": 1,
      "adjusted_price": 0
    }
  ],
  "sent_count": 1,
  "statement_descriptor": "string",
  "issue_date": 0,
  "due_date": 0,
  "amount": 45000,
  "amount_due": 45000,
  "discount_amount": 45000,
  "status": "draft",
  "charge": {
    "id": "obj_5f21c8a40b",
    "object": "string",
    "amount": 45000,
    "currency": "BIF",
    "description": "Room 204, two nights",
    "status": "succeeded",
    "source": {
      "id": "obj_5f21c8a40b",
      "brand": "ecocash",
      "funding": "credit",
      "last4": "string",
      "email": "jeanne@example.com",
      "fingerprint": "string",
      "token": "string",
      "language": "string",
      "number": "string",
      "cvc_check": "pass",
      "exp_month": "string",
      "exp_year": "string",
      "statement_descriptor": "string",
      "country_code": "string"
    },
    "affiliate": "dwelinn",
    "amount_refunded": 45000,
    "available_date": 0,
    "captured": false,
    "created_date": 0,
    "disputed": false,
    "failure_code": "string",
    "failure_message": "string",
    "invoice_id": "inv_7c1f9a2b48",
    "live": false,
    "modified_date": 0,
    "refunded": false,
    "customer_id": "cus_3d8e51fa20",
    "processing_id": "string",
    "quittance_number": "string"
  },
  "charges": [
    {
      "id": "obj_5f21c8a40b",
      "object": "string",
      "amount": 45000,
      "currency": "BIF",
      "description": "Room 204, two nights",
      "status": "succeeded",
      "source": {
        "id": null,
        "brand": null,
        "funding": null,
        "last4": null,
        "email": null,
        "fingerprint": null,
        "token": null,
        "language": null,
        "number": null,
        "cvc_check": null,
        "exp_month": null,
        "exp_year": null,
        "statement_descriptor": null,
        "country_code": null
      },
      "affiliate": "dwelinn",
      "amount_refunded": 45000,
      "available_date": 0,
      "captured": false,
      "created_date": 0,
      "disputed": false,
      "failure_code": "string",
      "failure_message": "string",
      "invoice_id": "inv_7c1f9a2b48",
      "live": false,
      "modified_date": 0,
      "refunded": false,
      "customer_id": "cus_3d8e51fa20",
      "processing_id": "string",
      "quittance_number": "string"
    }
  ],
  "type": "bank",
  "url": "string",
  "pdf_url": "string",
  "source_id": "src_0e7b3c95af",
  "manual_payment": false,
  "merchant": {
    "id": "obj_5f21c8a40b",
    "object": "string",
    "url": "string",
    "currency": "BIF",
    "name": "Jeanne Ndayishimiye",
    "legal_name": "Jeanne Ndayishimiye",
    "tax_id": "string",
    "phone_number": "+25779123456",
    "email": "jeanne@example.com",
    "registration_id": "string",
    "statement_descriptor": "string",
    "description": "Room 204, two nights",
    "support_url": "string",
    "time_zone": "AFRICA_BUJUMBURA",
    "type": "individual",
    "address": {
      "object": "string",
      "city": "string",
      "type": "personal",
      "status": "invalid",
      "state": "string",
      "country": "BI",
      "zip": "string",
      "line1": "string",
      "line2": "string"
    },
    "balance_available": 0,
    "balance_pending": 0,
    "status": "pending"
  },
  "live": false,
  "reference_id": "ref_9f2a17c4",
  "rate_id": "rat_20b6df3c9e",
  "total_amount_paid": 45000,
  "charge_ids": [
    {
      "chargeId": "chg_5a90bc71de",
      "accountType": "bank"
    }
  ],
  "quittance_number": "string"
}

Request body

application/json

Required. Send it as JSON.

descriptionstringrequired
Description of the invoice. Constraints: Not null, min=3 and max=120
Must be:3 to 120 characters
affiliatestring
affiliate that can be used on this invoice
Allowed values:dwelinn
sendForManualPaymentboolean
customer_idstringrequired
Customer Id. Constraints: Not null
productsarray of ItemRequestrequired
List of product and quantity. Constraints: Not null, Not Empty
- quantityinteger<int64>required
  Quantity for this product. Constraints: Not null
- product_idstringrequired
  Product Identifications. Constraints: Not Null
- rate_idsarray of string
  RateIds
due_datestring<date>required
Invoice due date. Constraints: Not null, format(YYYY-MM-DD)
source_idstring
Customer existing source information.
manual_paymentboolean
Collection Method of this invoice: If the payment is automatic then the system will charge against the customer register card. If it is manual the system will send an email to the customer with payment instruction.
rate_idstring
Rate Id that can be used on this invoice.
amount_to_paidnumber<double>
this is for partial payment of an invoice
custom_fieldsobject
Extra key/value pairs carried with the invoice. Every value has to be a string. For Burundi tax collection, set obr_code to the OBR payment code the payment belongs to, for example ADB_REGISTRE_COMMERCE. Leapa sends that code to OBR when the invoice is paid and puts the quittance number OBR issues on the invoice, as quittance_number. Write once: the invoice does not return custom_fields, and updating an invoice cannot change it, so keep your own record of which code you sent.
Example:{"obr_code":"ADB_REGISTRE_COMMERCE"}

Response

application/json

idstring
Generated Invoice Id by the system
objectstring
Invoice object.
customerCustomerResponse
- idstring
  Customer Unique ID
- objectstring
  Customer - Object Returned
- emailstring
  Customer email
- addressAddressResponse
- statusstring
  Customer Status
  Allowed values:activedeactivatedeleted
- first_namestring
  Customer firstname
- last_namestring
  Customer lastname
- birth_datestring
  Customer birthdate
- phone_numberstring
  Customer phone number
- merchant_namestring
  Merchant name associated to this Customer
- merchant_idstring
  Merchant ID associated to this Customer
- sourcesarray of AccountCustomerSourceReferenceResponse
  List of all Account Reference source of the customer
- destinationsarray of AccountCustomerDestinationReferenceResponse
  List of all Account Reference destination of the customer
- liveboolean
  Whether the object exist in live or test mode.
- reference_idstring
  Reference Id
currencystring
Currency of the amount in the invoice.
Allowed values:BIFUSDKESXAF
descriptionstring
Description of the invoice.
sendForManualPaymentboolean
automaticboolean
pdfLinkstring
numberstring
Invoice Number in a readable version for the user.
productsarray of ItemResponse
List of product and quantity.
- objectstring
  Name of the object
- productProductResponse
- quantityinteger<int64>
  Quantity billed in the invoice
- pricenumber<double>
  Price that the merchant will give to this product at the moment of the purchase.
- rate_idsarray of string
  RateIds
- discounted_pricenumber<double>
  Price with applied rate, if there are any rates applied
- adjusted_priceinteger<int64>
  Price that the merchant will give to this product at the moment of the purchase.
sent_countinteger<int32>
Number of time the invoice has been send to the customer for payment.
statement_descriptorstring
Statement Descriptor of the Merchant. This is a readOnly data.
issue_dateinteger<int64>
Invoice issue date.
due_dateinteger<int64>
Invoice due date.
amountinteger<int64>
Initial payment request amount to the customer for the service or product of the merchant.
amount_dueinteger<int64>
Remaining amount due in order to clear this Invoice.
discount_amountinteger<int64>
Amount of discount applied to the invoice.
statusstring
Status of the invoices: Draft, Pending, Paid, Void
Allowed values:draftpendingsentpaidpartial_paidvoidedoverduerefunded
chargeChargeResponse
- idstring
- objectstring
- amountinteger<int64>
- currencystring
  Allowed values:BIFUSDKESXAF
- descriptionstring
- statusstring
  Allowed values:succeededpaidpendingfailed
- sourceSourceObject
- affiliatestring
  Allowed values:dwelinn
- amount_refundedinteger<int64>
- available_dateinteger<int64>
- capturedboolean
- created_dateinteger<int64>
- disputedboolean
- failure_codestring
- failure_messagestring
- invoice_idstring
- liveboolean
- modified_dateinteger<int64>
- refundedboolean
- customer_idstring
- processing_idstring
- quittance_numberstring
chargesarray of ChargeResponse
Invoice Charges
- idstring
- objectstring
- amountinteger<int64>
- currencystring
  Allowed values:BIFUSDKESXAF
- descriptionstring
- statusstring
  Allowed values:succeededpaidpendingfailed
- sourceSourceObject
- affiliatestring
  Allowed values:dwelinn
- amount_refundedinteger<int64>
- available_dateinteger<int64>
- capturedboolean
- created_dateinteger<int64>
- disputedboolean
- failure_codestring
- failure_messagestring
- invoice_idstring
- liveboolean
- modified_dateinteger<int64>
- refundedboolean
- customer_idstring
- processing_idstring
- quittance_numberstring
typestring
Charge Account Type for Payment
Allowed values:bankbalancecardfeesmobilewalletcaships
urlstring
Invoice url
pdf_urlstring
Url link to download the PDF file of the invoice.
source_idstring
Customer existing source information.
manual_paymentboolean
Send invoice via email for manual payments.
merchantMerchantProfileResponse
- idstring
  Merchant Unique ID
- objectstring
  Return Object Name
- urlstring
  Optional field that describe the website URL of your business.
- currencystring
  Currency Code
  Allowed values:BIFUSDKESXAF
- namestring
  Business Name
- legal_namestring
  Legal Business Name
- tax_idstring
  Tax Id of the business
- phone_numberstring
- emailstring
- registration_idstring
  Commerce Reg Number
- statement_descriptorstring
  Statement Description
- descriptionstring
  Small description of your Goods or Services. Constraint: Not null, Not blank, size(5-22)
- support_urlstring
  Optional field that describe the website URL of the support pages.
- time_zonestring
  Time Zone of Merchant
  Allowed values:AFRICA_BUJUMBURAAFRICA_DOUALAAFRICA_NAIROBI
- typestring
  Holder Type
  Allowed values:individualcompany
- addressAddressResponseAccount
- balance_availableinteger<int64>
  Balance Aavailable for in this account
- balance_pendinginteger<int64>
  Pending balance in this account.
- statusstring
  Merchant Account Status
  Allowed values:pendingvalidation_in_progressvalidation_failedvalidated
liveboolean
Whether the object exist in live or test mode.
reference_idstring
Reference Id.
rate_idstring
Rate Id that can be used on this invoice.
total_amount_paidnumber<double>
Total Amount Paid for Partial payments
charge_idsarray of InvoiceChargeId
List of charges Ids linked to the invoice
- chargeIdstring
- accountTypestring
  Allowed values:bankbalancecardfeesmobilewalletcaships
quittance_numberstring
OBR quittance number generated for this invoice payment.

Status codes

201Created
400Bad request
401Unauthorized
402Payment required
403Forbidden
404Not found
428Precondition required
500Server error