Sign in

v1

latestOpenAPI 3.0.02026-07-2431146358.7 KB
Invoice

Create Invoice

An invoice represents the billed amount that needs to be collected from the customer for a subscription. This API can be used to create an invoice with the specific reference of the underlying mandateid.

The invoice details are sent to the customer as a pre-debit notification for the card and upi payment methods, as required by regulatory guidelines. For UPI, pre-debit-notifications are sent by bank via (sms, email)

To ensure that the pre-debit notification is received by the customer atleast 24 hours prior to the recurring charge (regulatory requirement), it is recommended that the invoice request is initiated 36 hrs prior to the recurring charge request.

If the recurring charge debit amount is higher than the permissible limit (as per regulations), the customer requires to provide an additional AFA for processing the recurring charge. This is not applicable for upi mandates

post/pgsi/ve1_2/invoice/create

Headers

BD-Traceidstring required
Example:20201203182838

BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.

BD-Timestampstring required
Example:20201203182838

Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.

Content-Typestring required
Example:application/json

Request Content-Type to take the values application/jose

Acceptstring required
Example:application/jose

Accept Response Content-Type to take the values application/jose

Request body

invoice_numberstring required

Unique number assigned by merchant for the invoice

invoice_display_numberstring required

Invoice number to be displayed to the customer

mercidstring required

Unique identifier as defined by BillDesk for each merchant

mandateidstring required

Unique mandateid created by BillDesk

currencystring required

ISO currency of the transaction amount, for INR this value will be 356

amountstring required

Invoice amount in two decimals, eg. 2400.00

subscription_refidstring required

Unique reference assigned by merchant for a subscription

customer_refidstring required

Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer Required for mandate and tokenization

debit_datestring date required

Date on which the SI debit needs to be executed to the payment method

invoice_datestring date required

Invoice generation date in the YYYYMMDD format

descriptionstring required

Brief description for the invoice

duedatestring date required

Invoice due date in the YYYYMMDD format

net_amountstring required

Current payable amount, adjusted for discount or late payment charges as applicable

early_payment_amountstring

Amount after adjusting any discount applicable.

early_payment_discountstring

Discount amount for early payment of invoice

early_payment_duedatestring date

Early payment date for invoice

late_payment_amountstring

Payment amount after due date

late_payment_chargesstring

Late payment charges if any

Example request

{
  "invoice_number": "INVNUM0000001",
  "invoice_display_number": "DISINVNUM0001",
  "mercid": "BDMERCID",
  "mandateid": "MA19E400049927",
  "amount": "2400.00",
  "subscription_refid": "SUBREF101",
  "customer_refid": "CSREF00001",
  "debit_date": "2023-03-20",
  "invoice_date": "2023-04-22",
  "description": "Debit for Plan 499",
  "duedate": "2023-06-17",
  "net_amount": "2.00",
  "early_payment_amount": "490.00",
  "early_payment_discount": "10.00",
  "early_payment_duedate": "2021-05-12",
  "late_payment_amount": "520.00",
  "late_payment_charges": "20.00",
  "additional_info": {
    "additional_info1": "Details1",
    "additional_info2": "Details2",
    "additional_info3": "Details3",
    "additional_info4": "Details4",
    "additional_info5": "Details5",
    "additional_info6": "Details6",
    "additional_info7": "Details7"
  }
}

Response

OK

objectid'transaction' | 'authentication' | 'mandate' | 'invoice' | 'cardaccount' | 'validatevpa' | 'dispute' | 'settlement' | 'altid' | 'mandate_token' | 'accountvalidation'

String representing the object's type. Objects of the same type share the same value.

invoice_numberstring

Unique number assigned by merchant for the invoice

invoice_display_numberstring

Invoice number to be displayed to the customer

mercidstring

Unique identifier as defined by BillDesk for each merchant

subscription_refidstring

Unique reference assigned by merchant for a subscription

customer_refidstring

Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer Required for mandate and tokenization

invoice_datestring date

Invoice generation date in the YYYYMMDD format

duedatestring date

Invoice due date in the YYYYMMDD format

debit_datestring date

Date on which the SI debit needs to be executed to the payment method

amountstring

Invoice amount in two decimals, eg. 2400.00

net_amountstring

Current payable amount, adjusted for discount or late payment charges as applicable

early_payment_due_datestring date

Early payment date for invoice

early_payment_discountstring

Discount amount for early payment of invoice

early_payment_amountstring

Amount after adjusting any discount applicable.

late_payment_chargesstring

Late payment charges if any

late_payment_amountstring

Payment amount after due date

currencystring

ISO currency of the transaction amount, for INR this value will be 356

mandateidstring

Unique mandateid created by BillDesk

descriptionstring

Brief description for the invoice

status'unpaid' | 'rejected' | 'stopped'

Status of the invoice. Possible values are: • unpaid – invoice has been received successfully, and charge can be processed • rejected – invoice has been rejected by the system • stopped – invoice has been stopped by the customer

invoice_idstring

Unique id created by BillDesk for each invoice

verification_error_codestring

Represents the error code for the response

verification_error_typestring

Represents the error type for the response

verification_error_descstring

Represents the error description for the response

createdonstring date-time

object creation timestamp

Example response

{
  "invoice_number": "INVNUM0000001",
  "invoice_display_number": "DISINVNUM0001",
  "mercid": "BDMERCID",
  "subscription_refid": "SUBREF101",
  "customer_refid": "CSREF00001",
  "invoice_date": "2023-04-22",
  "duedate": "2023-06-17",
  "debit_date": "2023-03-20",
  "amount": "2400.00",
  "net_amount": "2.00",
  "early_payment_due_date": "2021-05-12",
  "early_payment_discount": "10.00",
  "early_payment_amount": "490.00",
  "late_payment_charges": "20.00",
  "late_payment_amount": "520.00",
  "mandateid": "MA19E400049927",
  "description": "Debit for Plan 499",
  "invoice_id": "IA047F00003663",
  "additional_info": {
    "additional_info1": "Details1",
    "additional_info2": "Details2",
    "additional_info3": "Details3",
    "additional_info4": "Details4",
    "additional_info5": "Details5",
    "additional_info6": "Details6",
    "additional_info7": "Details7"
  }
}