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


In this article you will be going to know about:


Create Invoice


Sample Request Payload

Posthttps://{{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": "Riyadh",
        "country": "SA"
    },
    "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.clickpay.com.sa/payment/request/invoice/1320598/C959A415A47D4E3E8F5000000AAAAABBBBCCCCADE9A01"
}

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


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

{ 
  "tran_ref": "SFT222221111100000",
  "merchant_id": 515151515,
  "profile_id": 61616161616,
  "cart_id": "cart_12345",
  "cart_description": "Test Description",
  "cart_currency": "SAR",
  "cart_amount": "9.50",
  "tran_currency": "SAR",
  "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": "SA",
    "ip": "10.0.0.1"
  },
   "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

Posthttps://{{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.clickpay.com.sa/payment/request/invoice/1320598/C959A415A47D4E3000111222333E9A01"
}

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


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": "SFT222221111100000",
  "merchant_id": 515151515,
  "profile_id": 61616161616,
  "cart_id": "cart_12345_2",
   "cart_description": "Test Description",
  "cart_currency": "SAR",
  "cart_amount": "9.50",
  "tran_currency": "SAR",
  "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": "8.8.8.8"
  },
   "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

Gethttps://{{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": "SFT200001111000076067",
    "tran_status": "A",
     "tran_status_msg": "Authorised"
}

Canceled Invoice Response Sample 

{
    "invoice_status": "cancelled"
}


POST

Sample Request Payload

Posthttps://{{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": "SFT2222221111100000",
    "tran_status": "A",
     "tran_status_msg": "Authorised"
}

Canceled Invoice Response Sample

{
    "invoice_status": "cancelled"
}

Cancel Invoice


PUT

Sample Request Payload

Puthttps://{{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

Posthttps://{{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"
}