Creating an Invoice

API Documentation for Creating an Invoice

This document instructs developers on creating an invoice using the provided API. Follow the steps carefully to ensure a successful request.

Endpoint

URL: /api/merchants/{merchantId}/invoices
Method: POST
Content-Type: application/json

Description

This API endpoint allows you to create an invoice for a specific merchant. The merchant is identified by the merchantId parameter in the URL. The invoice details are provided in the request body in JSON format.

Request URL

Replace {merchantId} with the actual merchant ID.

https://api.paylink.sa/api/merchants/{merchantId}/invoices

HTTP Method

POST

Request Headers

Content-Type: application/json
X-API-KEY: your_api_key

Request Body

The request body must be in JSON format and include the following fields:

invoiceNumber (string): A unique identifier for the invoice. Example: "INV-1001"
dueDate (string): The date by which the invoice should be paid, in YYYY-MM-DD format. Example: "2024-07-31"
items (array of objects): An array of items included in the invoice. Each item object should contain:
- description (string): Description of the item. Example: "Web Development Services"
- quantity (number): Quantity of the item. Example: 1
- price (number): Price per item. Example: 5000
totalAmount (number): The total amount for the invoice. Example: 5200
currency (string): The currency of the invoice. Example: "SAR"
customerInfo (object): Information about the customer. It should contain:
- customerName (string): Name of the customer. Example: "Customer XYZ"
- customerPhone (string): Phone number of the customer in the format 966XXXXXXXXX. Example: "966123456789"
callbackUrl (string): A URL that will be called after the invoice is created. Example: "https://yourcallbackurl.com/invoice-created"

Example Request Body:

{
  "invoiceNumber": "INV-1001",
  "dueDate": "2024-07-31",
  "items": [
    {
      "description": "Web Development Services",
      "quantity": 1,
      "price": 5000
    },
    {
      "description": "Hosting Services",
      "quantity": 1,
      "price": 200
    }
  ],
  "totalAmount": 5200,
  "currency": "SAR",
  "customerInfo": {
    "customerName": "Customer XYZ",
    "customerPhone": "966123456789"
  },
  "callbackUrl": "https://yourcallbackurl.com/invoice-created"
}

Example `curl` Command

curl -X POST https://api.paylink.sa/api/merchants/{merchantId}/invoices \
-H "Content-Type: application/json" \
-H "X-API-KEY: your_api_key"
-d '{
  "invoiceNumber": "INV-1001",
  "dueDate": "2024-07-31",
  "items": [
    {
      "description": "Web Development Services",
      "quantity": 1,
      "price": 5000
    },
    {
      "description": "Hosting Services",
      "quantity": 1,
      "price": 200
    }
  ],
  "totalAmount": 5200,
  "currency": "SAR",
  "customerInfo": {
    "customerName": "Customer XYZ",
    "customerPhone": "966123456789"
  },
  "callbackUrl": "https://yourcallbackurl.com/invoice-created"
}'

Replace {merchantId} with the actual merchant ID in the URL.

Success Response

If the request is successful, you will receive a 201 Created status code with the following response body:

{
  "message": "Invoice created successfully",
  "invoiceId": "unique_invoice_id"
}

Error Response

If there is an error in the request, you will receive a 400 Bad Request status code with an error message:

{
  "message": "Invalid request data"
}

Common Issues and Troubleshooting

Invalid Merchant ID: Ensure that you have replaced the{merchantId} with the correct merchant ID.
Incorrect Phone Format: Verify that the phone number is in the correct format (966XXXXXXXXX).
Missing Required Fields: Ensure all required fields are included in the request body.
Incorrect URL: Double-check the URL to ensure it is correct.

By following these steps and using the provided documentation, you should be able to create an invoice successfully using the API.