Test Invoice

Create a new Invoice

post

Create a new Invoice example

Authentication Notes

The Api-Key is already automatically added to the headers, so no authentication type required.

If you want to choose your preferred authentication type, follow these steps:

Deselect the Api-Key header and choose one of the following:
- For ApiKeyAuth, use: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo.
- For BasicAuth, provide your valid username and password.
- For JWT Auth, include your token in the format: Bearer <your_token>.

Authorizations

AuthorizationstringRequired

HTTP API Key Authentication

API-Key authentication for private use only.

Example API-Key

vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo

Example Header:

Authorization: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo

Header parameters

AuthorizationstringRequired

Private API key to be provided in the format Api-Key <key>.

Default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo

Body

Serializer class for Invoice instances, inheriting from BaseInvoiceSerializer and CheckoutSerializer. It provides methods for creating invoices, invoice items, and transactions.

currency_codestring · min: 1Required

due_datestring · dateRequired

invoice_numberstring · min: 1 · max: 255Required

pg_codesstring[]Required

typestring · enumRequired

e_commerce - Ecommerce
payment_request - Payment Request

Possible values:

Responses

201Success

application/json

Serializer class for Invoice instances, inheriting from BaseInvoiceSerializer and CheckoutSerializer. It provides methods for creating invoices, invoice items, and transactions.

currency_codestringRequired

The specified currency represents the denomination of the transaction.Nevertheless, it doesn't necessarily mandate payment in this exact currency.Due to potential currency conversions or exchanges, the final charge may be in a different currency.

due_datestring · dateRequired

The date by which the customer is expected to make payment for the invoice.

invoice_numberstring · max: 255Required

A unique identifier for the invoice, typically used for tracking and referencing purposes.

pg_codesstring[]Required

The list of payment gateway codes from which a customer can select to perform the payment

typestring · enumRequired

The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices.

e_commerce - Ecommerce
payment_request - Payment Request

Possible values:

amountstring · decimalOptional

Represents the total amount of the payment transaction, which includes the cost of the purchased items or services but excludes any additional fees or charges

attachmentstring · uriOptional

A writable field that accepts an attachment file to be included in email notifications sent to the customer regarding their payment, and also be available for download on the checkout page. This field may be used to provide the customer with additional information or documentation related to their purchase. The value of this field should be a file object. Upon successful submission, the API will return the URL for downloading the attached file.

attachment_short_urlstring · uriRead-onlyRequired

A short URL that links to the attachment associated with this payment. This URL may be included in email/sms notifications sent to the customer regarding their payment or displayed on the checkout page to allow the customer to easily access the attachment.

attachment_upload_urlstringOptional

A writable field that accepts an attachment that has already been uploaded to the server.

Pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$

checkout_short_urlstring · uriRead-onlyRequired

A short URL link that, when opened, redirects to the checkout page for this payment. This URL may be shared with the customer to allow them to easily access and complete the payment. This field is only available if the shortify_checkout_url field is set to True.

checkout_urlstring · uriRead-onlyRequired

URL that directs the customer to the Ottu Checkout Page where they can see the payment details and available payment methods for the transaction. If you need to share the payment link over SMS or WhatsApp, use checkout_short_url instead.

company_namestring · max: 64Optional

The company name is used for invoice API.

customer_emailstring · email · max: 128Optional

The email address of the customer that is used to send payment notifications and receipts, and can be used for fraud prevention. This field is mandatory and is always sent to the payment gateway. It may also be included in the invoice, receipt, email, and displayed on the payment page.

customer_first_namestring · max: 64Optional

The first name of the recipient of the payment. This field is used for various communications such as the invoice, receipt, email, SMS, or displayed on the payment page. It may also be sent to the payment gateway if necessary.

customer_idstring · max: 64Optional

The customer ID is a unique identifier for the customer within the merchant's system. It is also used as a merchant identifier for the customer and plays a critical role in tokenization. All the customer's cards will be associated with this ID.

customer_last_namestring · max: 64Optional

The last name of the recipient of the payment. This field is used for various communications such as the invoice, receipt, email, SMS, or displayed on the payment page. It may also be sent to the payment gateway if necessary.

customer_phonestring · max: 16Optional

Customer phone number associated with the payment. This might be sent to the payment gateway and depending on the gateway, it may trigger a click to pay process on the payment page. The phone number will also be included in the invoice, receipt, email, and displayed on the payment page.

discount_amountstring · decimalOptional

The fixed amount discount applied to the full invoice amount, including taxes. If set, the discount_percentage field will be set to null. Both discount_amount and discount_percentage cannot be set simultaneously. The discount cannot be higher than the total_excl_tax field.

discount_percentagestring · decimalOptional

The percentage-based discount applied to the full invoice amount, including taxes. If set, the discount_amount field will be automatically calculated. Both discount_amount and discount_percentage cannot be set simultaneously. The discount cannot be higher than the total_excl_tax field.

due_datetimestring · date-timeOptional

The date and time by which the payment is due. This field may be used to help remind the customer to complete the payment before the due date.

email_recipientsstring · email[]Optional

A comma-separated list of email addresses for internal recipients who will receive customer emails. These recipients will be included in email notifications sent to the customer regarding their payment.

expiration_timestringOptional

If defined, any payment transactions created more than the specified period of time ago will be invalidated or expired if the customer attempts to complete them. By default, this expiration period is set to 24 hours from the time of transaction creation. This feature helps ensure that payment transactions are processed promptly.

initiator_idintegerOptional

The user who initiated the creation of this payment transaction, if available. This field is optional and may be used to track who created the payment transaction. Note that if the payment transaction was using API Key auth initiator_id can be set to any value that corresponds to an existing ACTIVE user in the system

invoice_idintegerRead-onlyRequired

languagestring · enumOptional

This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction.

en - English
ar - Arabic

Default: enPossible values:

operationstringRead-onlyRequired

Specifies the type of operation to be performed by the payment gateway. If set to purchase, the payment source will be directly charged. If set to authorize, the payment source will only be authorized and the actual charge will be made at a later time.

order_nostring · max: 128Optional

The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.

payment_typestring · enumOptional

Type of payment. Choose one_off for payments that occur only once without future commitments. Choose auto_debit for payments that are automatically deducted, such as recurring subscriptions, installments, or unscheduled auto-debits.

Choose save_card if you want to perform a card tokenization operation.

NOTE: If auto_debit is selected:

agreement and customer_id parameters will also be mandatory.
Only PG codes supporting tokenization can be selected. As a side effect, the card used for the payment will be associated with the supplied agreement.id. This card will be locked, preventing the customer from deleting it from the system until an alternate card is chosen for auto-debit payments.

NOTE: If save_card is selected:

The amount must be zero for the save card operation.
The selected MID(pg_code) must support tokenization to enable the save card operation.
Please note that the save card operation is considered successful without any funds being charged.
Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.

one_off - One Off
auto_debit - Auto Debit
save_card - Save Card

Default: one_offPossible values:

product_typestring · max: 128Optional

The type of product or service being purchased. This field may be used for tracking and reporting purposes.

qr_code_urlstring · uriRead-onlyRequired

A QR code that, when scanned, redirects to the checkout page for this payment. This QR code may be displayed on invoices, receipts, or other documents to allow customers to easily access the checkout page and make a payment. This parameter is only present when generate_qr_code is set to true.

redirect_urlstring · uri · max: 2000Optional

The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. order_no, reference_number and session_id will be appended to the redirect URL as query parameters.

session_idstringRead-onlyRequired

A unique identifier for each payment transaction, used to maintain the session state during the payment process.

settled_pg_codestringRead-onlyRequired

The code of the payment gateway used for completing the transaction. This field indicates the specific gateway that processed and settled the payment, providing clarity on which payment service was ultimately utilized for this transaction.

shipping_excl_taxstring · decimalOptional

The cost of shipping for the invoice, excluding taxes.

shipping_incl_taxstring · decimalOptional

The cost of shipping for the invoice, including all applicable taxes.

shipping_methodstringOptional

The method or service used for shipping the items associated with the invoice.

shipping_tax_ratestring · decimalOptional

The tax rate applied to the shipping cost, expressed as a percentage.

statestring · enumRead-onlyRequired

The current state of the payment transaction, it helps to understand the progress of the payment.

created - Created
pending - Pending
attempted - Attempted
authorized - Authorized
paid - Paid
failed - Failed
canceled - Canceled
expired - Expired
invalided - Invalided
refunded - Refunded
cod - Cash on Delivery

Possible values:

statusstring · enumRead-onlyRequired

Current status of the invoice. Can be one of the following: sent, paid, overdue, canceled.

sent - Sent
paid - Paid
overdue - Overdue
canceled - Canceled

Possible values:

subtotalstring · decimalOptional

Sum of total_incl_tax's of all invoice items.

tax_amountstring · decimalOptional

The total amount of tax applied to the invoice.

tax_ratestring · decimalOptional

The tax rate applied to the invoice, expressed as a percentage.

total_excl_taxstring · decimalOptional

The total amount of the invoice, excluding taxes.

total_incl_taxstring · decimalOptional

The total amount of the invoice, including all applicable taxes.

vendor_namestring · max: 64Optional

The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes.

webhook_urlstring · uri · max: 2000Optional

URL where the payment result will be sent via a POST request after the customer has completed the payment session. The payment result will be included in the request body.

400Error

application/json

post

/b/invoice/v1/invoice/

POST /b/invoice/v1/invoice/ HTTP/1.1
Host: betabulk.ottu.net
Authorization: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo
Content-Type: application/json
Accept: */*
Content-Length: 237

{
  "type": "payment_request",
  "due_date": "2024-12-29",
  "currency_code": "KWD",
  "pg_codes": [
    "knet",
    "mpgs"
  ],
  "invoice_number": "<add `invoice_number` here>",
  "invoice_items": [
    {
      "sku": "ABC111",
      "description": "Tea",
      "quantity": 1.111,
      "unit_price": 0.234
    }
  ]
}

{
  "currency_code": "text",
  "due_date": "2026-03-30",
  "invoice_items": [
    {
      "id": 1,
      "invoice": 1,
      "sku": "text",
      "description": "text",
      "quantity": "text",
      "unit_price": "text",
      "tax_rate": "text",
      "tax_amount": "text",
      "discount_percentage": "text",
      "discount_amount": "text",
      "total_excl_tax": "text",
      "total_incl_tax": "text",
      "currency_code": "text"
    }
  ],
  "invoice_number": "text",
  "pg_codes": [
    "text"
  ],
  "type": "e_commerce",
  "billing_address": {
    "line1": "text",
    "line2": "text",
    "city": "text",
    "state": "text",
    "country": "AF",
    "postal_code": "text"
  },
  "shipping_address": {
    "line1": "text",
    "line2": "text",
    "city": "text",
    "state": "text",
    "country": "AF",
    "postal_code": "text",
    "first_name": "text",
    "last_name": "text",
    "email": "name@gmail.com",
    "phone": "text"
  },
  "agreement": {
    "id": "text",
    "amount_variability": "fixed",
    "start_date": "2026-03-30",
    "expiry_date": "2026-03-30",
    "max_amount_per_cycle": "text",
    "cycle_interval_days": 1,
    "total_cycles": 1,
    "frequency": "irregular",
    "type": "recurring",
    "seller": {
      "name": "text",
      "short_name": "text",
      "category_code": "text"
    },
    "extra_params": {
      "payment_processing_day": 1
    }
  },
  "amount": "text",
  "attachment": "https://example.com",
  "attachment_short_url": "https://example.com",
  "attachment_upload_url": "text",
  "card_acceptance_criteria": {
    "min_expiry_time": 1
  },
  "checkout_short_url": "https://example.com",
  "checkout_url": "https://example.com",
  "company_name": "text",
  "customer_email": "name@gmail.com",
  "customer_first_name": "text",
  "customer_id": "text",
  "customer_last_name": "text",
  "customer_phone": "text",
  "discount_amount": "text",
  "discount_percentage": "text",
  "due_datetime": "2026-03-30T05:10:24.410Z",
  "email_recipients": [
    "name@gmail.com"
  ],
  "expiration_time": "text",
  "initiator_id": 1,
  "invoice_id": 1,
  "language": "en",
  "notifications": {
    "email": [
      "created"
    ],
    "sms": [
      "created"
    ],
    "whatsapp": [
      "created"
    ]
  },
  "operation": "text",
  "order_no": "text",
  "payment_methods": {
    "code": "text",
    "name": "text",
    "pg": "text",
    "type": "e_commerce",
    "amount": "text",
    "currency_code": "text",
    "fee": "text",
    "fee_description": "text",
    "icon": "https://example.com",
    "flow": "redirect",
    "redirect_url": "https://example.com"
  },
  "payment_type": "one_off",
  "product_type": "text",
  "qr_code_url": "https://example.com",
  "redirect_url": "https://example.com",
  "sdk_setup_preload_payload": false,
  "session_id": "text",
  "settled_pg_code": "text",
  "shipping_excl_tax": "text",
  "shipping_incl_tax": "text",
  "shipping_method": "text",
  "shipping_tax_rate": "text",
  "state": "created",
  "status": "sent",
  "subtotal": "text",
  "tax_amount": "text",
  "tax_rate": "text",
  "total_excl_tax": "text",
  "total_incl_tax": "text",
  "vendor_name": "text",
  "webhook_url": "https://example.com"
}

Back

Last updated 1 year ago

hashtagCreate a new Invoice

Create a new Invoice example

HTTP API Key Authentication

Example API-Key

Example Header:

Create a new Invoice