Invoices APIs enable you to create, cancel or query any invoice you want. You may have the same functionality available via Invoices on PayTabs Merchant Dashboard also it is available via APIs.


In this article you will be going to know about:


Create Invoice


Sample Request Payload


Post

https://{{domain}}/payment/new/invoice

 

{
    "profile_id": {{profile_id}},
    "tran_type": "sale",
    "tran_class": "ecom",
     "cart_currency": "{{currency}}",
    "cart_amount": "9.5",
    "cart_id": "cart_12345",
     "cart_description": "Test Description",
     "hide_shipping": true,
     "customer_ref":"CUST0101",
     "customer_details": {
        "name": "First Last",
        "email": "[email protected]",
        "street1": "404, 11th st, void",
        "city": "Dubai",
        "country": "AE"
    },
    "invoice": {
         "shipping_charges": 0,
         "extra_charges": 0,
         "extra_discount": 0,
         "total": 0,
         "activation_date": "2021-09-05T15:58:20+04:00",
         "expiry_date": "2021-09-27T13:33:00+04:00",
         "due_date": "2021-09-26T12:36:00+04:00",
         "line_items": [
            {
                 "sku": "sku",
                 "description": "desc",
                 "url": "https://www.coffeecoffeecoffee.com/whats-new/flat-white",
                 "unit_cost": 9.5,
                 "quantity": 1,
                 "net_total": 9.5,
                 "discount_rate": 0,
                 "discount_amount": 0,
                 "tax_rate": 0,
                 "tax_total": 0,
                "total": 9.5
            }
        ]
    },
    "callback": "{{callback_url}}",
    "return": "{{return_url}}"
}


Sample Response Payload


{ 
    "invoice_id": 10000010001,
    "invoice_link": "https://secure.paytabs.com/payment/request/invoice/1320598/C959A415A47D4E3E8F5000000AAAAABBBBCCCCADE9A01"
}


Once the activation date begins, the payment will be available to proceed

Graphical user interface, application

Description automatically generated



Then after it's proceeded, the callback payload will be sent to the URL defined in the "callback_url"

{ 
  "tran_ref": "TST222221111100000",
  "merchant_id": 515151515,
  "profile_id": 61616161616,
  "cart_id": "cart_12345",
  "cart_description": "Test Description",
  "cart_currency": "USD",
  "cart_amount": "9.50",
  "tran_currency": "USD",
  "tran_total": "9.50",
  "tran_type": "Sale",
  "tran_class": "ECom",
  "customer_details": {
   "name": "First Last",
    "email": "[email protected]",
    "street1": "Unknown",
    "city": "Unknown",
    "state": "C",
    "country": "EG",
    "ip": "41.33.38.98"
  },
   "payment_result": {
     "response_status": "A",
     "response_code": "G22680",
     "response_message": "Authorised",
    "cvv_result": " ",
    "avs_result": " ",
     "transaction_time": "2021-12-02T12:58:00Z"
  },
  "payment_info": {
     "payment_method": "Visa",
    "card_type": "Credit",
    "card_scheme": "Visa",
     "payment_description": "4000 00## #### 0002",
    "expiryMonth": 12,
    "expiryYear": 2022
  },
  "ipn_trace": "IPNS0004.6100008.00004D4D"
}

 


Create Invoice with Tokenization


Sample Request Payload


Post

https://{{domain}}/payment/new/invoice

 

{
    "profile_id": {{profile_id}},
    "tran_type": "sale",
    "tran_class": "ecom",
    "tokenise": 2,
    "cart_currency": "{{currency}}",
    "cart_amount": "9.5",
    "cart_id": "cart_12345_2",
     "cart_description": "Test Description",
     "hide_shipping": true,
     "customer_ref":"CUST0101",
    "invoice": {
         "shipping_charges": 0,
        "extra_charges": 0,
         "extra_discount": 0,
        "total": 0,
         "activation_date": "2021-07-25T12:35:20+04:00",
         "expiry_date": "2021-07-27T13:33:00+04:00",
         "due_date": "2021-07-26T12:36:00+04:00",
         "line_items": [
            {
                 "sku": "sku",
                 "description": "desc",
                 "url": "https://www.coffeecoffeecoffee.com/whats-new/flat-white",
                 "unit_cost": 9.5,
                 "quantity": 1,
                 "net_total": 9.5,
                 "discount_rate": 0,
                 "discount_amount": 0,
                 "tax_rate": 0,
                 "tax_total": 0,
                 "total": 9.5
            }
        ]
    },
    "callback": "{{callback_url}}",
    "return": "{{return_url}}"
} 


Sample Response Payload

{ 
    "invoice_id": 111111222223333,
     "invoice_link": "https://secure.paytabs.com/payment/request/invoice/1320598/C959A415A47D4E3000111222333E9A01"
}


Once the activation date begins, the payment will be available to proceed

Graphical user interface, application

Description automatically generated


Then after it's proceeded, the callback payload will be sent to the URL defined in the "callback_url"

There is a token that included on the response object, which can be used later with any direct payment request (recurring payment)


{ 
  "tran_ref": "TST222221111100000",
  "merchant_id": 515151515,
  "profile_id": 61616161616,
  "cart_id": "cart_12345_2",
   "cart_description": "Test Description",
  "cart_currency": "USD",
  "cart_amount": "9.50",
  "tran_currency": "USD",
  "tran_total": "9.50",
  "tran_type": "Sale",
  "tran_class": "ECom",
   "customer_details": {
    "name": "John Doe",
    "email": "[email protected]",
    "street1": "Unknown",
    "city": "Unknown",
    "state": "C",
    "country": "FR",
    "ip": "41.33.38.98"
  },
   "payment_result": {
     "response_status": "A",
     "response_code": "G23798",
     "response_message": "Authorised",
    "cvv_result": " ",
    "avs_result": " ",
     "transaction_time": "2021-12-04T13:16:38Z"
  },
  "payment_info": {
     "payment_method": "Visa",
    "card_type": "Credit",
    "card_scheme": "Visa",
     "payment_description": "4000 00## #### 0002",
    "expiryMonth": 12,
    "expiryYear": 2022
  },
  "token": "2C4612345678436C123456796C867ABA",
  "ipn_trace": "IPNS0003.60000A36.00004D6D"
}

Query Invoice Status


GET


Sample Request Payload


GET

https://{{domain}}/payment/invoice/{{invoice_id}}/status



Sample Response Payload


Pending Invoice Response Sample

{
     "invoice_status": "pending"
}

 

Paid Invoice Response Sample 

{
     "invoice_status": "paid",
    "tran_ref": "TST200001111000076067",
    "tran_status": "A",
     "tran_status_msg": "Authorised"
}


Canceled Invoice Response Sample 

{
    "invoice_status": "cancelled"
}

 


POST

Sample Request Payload


POST

https://{{domain}}/payment/invoice/status

{
    "profile_id": {{profile_id}},
    "invoice_id": {{invoice_id}}
}



Sample Response Payload


Pending Invoice Response Sample 

{
     "invoice_status": "pending"
}

 

Paid Invoice Response Sample 

{
     "invoice_status": "paid",
    "tran_ref": "TST2222221111100000",
    "tran_status": "A",
     "tran_status_msg": "Authorised"
}


Canceled Invoice Response Sample 

{
    "invoice_status": "cancelled"
}

 


Cancel Invoice


PUT


Sample Request Payload

PUT

https://{{domain}}/payment/invoice/{{invoice_id}}/cancel




Sample Response Payload


Success Canceling Invoice Response Sample

{
    "message": "Invoice has been cancelled"
}

 

Failed to Cancel Invoice Response Sample


{
    "code": 500,
    "message": "Failed to cancel invoice"
}


POST


Sample Request Payload


POST

https://{{domain}}/payment/invoice/status


{
    "profile_id": {{profile_id}},
    "invoice_id": {{invoice_id}}
}



Sample Response Payload


Success Canceling Invoice Response Sample


{
    "message": "Invoice has been cancelled"
}

 

Failed to Cancel Invoice Response Sample


{
    "code": 500,
    "message": "Failed to cancel invoice"
}