Skip to main content
POST
/
v1
/
invoices
cURL
curl --request POST \
  --url https://api.paycashless.com/v1/invoices \
  --header 'Content-Type: application/json' \
  --header 'Request-Signature: <request-signature>' \
  --header 'Request-Timestamp: <request-timestamp>' \
  --data '{
  "reference": "<string>",
  "acceptPartialPayments": false,
  "description": "<string>",
  "currency": "NGN",
  "sendEmail": false,
  "autoFinalize": true,
  "callbackUrl": "https://example.com/callback",
  "returnUrl": "https://example.com/return",
  "customer": {
    "email": "jsmith@example.com",
    "name": "<string>",
    "address": "<string>"
  },
  "items": [
    {
      "name": "<string>",
      "quantity": 123,
      "description": "<string>",
      "price": 100000
    }
  ],
  "taxRateIds": [
    "txr_1"
  ],
  "maxInstallments": 3,
  "daysUntilDue": 30,
  "metadata": {
    "customer_id": "123",
    "order_id": "456"
  }
}'
{
  "id": "<string>",
  "status": "draft",
  "customerId": "<string>",
  "description": "<string>",
  "currency": "NGN",
  "reference": "<string>",
  "sendEmail": true,
  "dueDate": "2023-11-07T05:31:56Z",
  "liveMode": true,
  "number": "0001",
  "amountDue": 100000,
  "amountPaid": 100000,
  "totalInclusiveTaxAmount": 10000,
  "totalExclusiveTaxAmount": 10000,
  "taxRateIds": [
    "tax_rate_1"
  ],
  "items": [
    {
      "id": "<string>",
      "name": "<string>",
      "quantity": 123,
      "price": 1000
    }
  ],
  "maxInstallments": 3,
  "hostedInvoiceUrl": "https://invoicing.paycashless.com/inv_123"
}

Headers

​
Request-Signature
string
required

SHA-512 HMAC signature of the request payload using the API secret

Minimum length: 1
Example:

"5e73d044c44d733fcf819ad3409aaaddca840d421b69cb0b04e2c750fc62ece7526d36296237663ad1f06f62a730c0466516507196b3ce6567493cc52a7cf63d"

​
Request-Timestamp
string
required

UNIX timestamp when the request was created (in seconds)

Example:

"1712336881"

Body

application/json
​
reference
string
required
​
description
string
required
​
currency
enum<string>
required
Available options:
NGN,
USD
​
customer
object
required
​
items
object[]
required
Maximum length: 20
​
daysUntilDue
integer
required

The number of days until the invoice is due

Required range: 0 < x <= 1800
Example:

30

​
acceptPartialPayments
boolean
default:false
​
sendEmail
boolean
default:false
​
autoFinalize
boolean
default:false

Whether to automatically finalize the invoice, invoice will be in draft state if this is false

Example:

true

​
callbackUrl
string<uri>

The URL to call when the invoice is paid

Example:

"https://example.com/callback"

​
returnUrl
string<uri>

The URL to redirect to when the invoice is paid

Example:

"https://example.com/return"

​
taxRateIds
string[]

The tax rates to apply to the invoice

Example:
["txr_1"]
​
maxInstallments
number
default:1

The maximum number of installments the customer can pay in, only required when acceptPartialPayments is true

Example:

3

​
metadata
object

Additional metadata for the invoice

Example:
{ "customer_id": "123", "order_id": "456" }

Response

201 - application/json

Invoice created successfully

​
id
string
required
​
status
enum<string>
required
Available options:
draft,
open,
paid,
partially_paid,
cancelled
​
customerId
string
required
​
description
string
required
​
currency
enum<string>
required
Available options:
NGN,
USD
​
reference
string
required
​
sendEmail
boolean
required
​
dueDate
string<date-time>
required
​
liveMode
boolean
required
​
number
string
required

The number of the invoice

Example:

"0001"

​
amountDue
integer
required

The total amount due for the invoice in smallest currency unit

Required range: x > 0
Example:

100000

​
amountPaid
integer
required

The total amount paid for the invoice in smallest currency unit

Required range: x > 0
Example:

100000

​
totalInclusiveTaxAmount
integer
required

The total inclusive tax amount for the invoice in smallest currency unit

Required range: x > 0
Example:

10000

​
totalExclusiveTaxAmount
integer
required

The total exclusive tax amount for the invoice in smallest currency unit

Required range: x > 0
Example:

10000

​
taxRateIds
string[]
required

The tax rates applied to the invoice

Example:
["tax_rate_1"]
​
items
object[]
required
​
hostedInvoiceUrl
string<uri>
required

The URL to the hosted invoice payment page

Example:

"https://invoicing.paycashless.com/inv_123"

​
maxInstallments
number

The maximum number of installments the customer can pay in

Example:

3