Send an Invoice

API Documentation for Sending an Invoice Link

This document provides detailed instructions for developers on how to send an invoice link using the provided API. Follow the steps carefully to ensure a successful request.

Endpoint

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

Description

This API endpoint allows you to send an invoice link to the contacts via email, SMS, or WhatsApp. The invoice can be specified by invoiceId or by providing the full invoice body.

Request URL

Replace {merchantId} with the actual merchant ID.

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

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:

• invoice (object): Contains either the invoiceId or the full invoice body.
  • invoiceId (string): The unique identifier for the invoice. Example: "unique_invoice_id"
    OR
  • 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"
• contacts (array of objects): An array of contact objects. Each contact object should contain:
  • type (string): The type of contact, either "email", "sms", or "whatsapp".
  • contact (string): The contact information (email address or phone number). Example: "[email protected]" or "966123456789"
• message (string): Optional to include with the invoice link. Example: "Dear Customer, please find the invoice link below."

Example Request Body:

{
  "invoice": {
    "invoiceId": "unique_invoice_id"
  },
  "contacts": [
    {
      "type": "email",
      "contact": "[email protected]"
    },
    {
      "type": "sms",
      "contact": "966123456789"
    },
    {
      "type": "whatsapp",
      "contact": "966123456789"
    }
  ],
  "message": "Dear Customer, please find the invoice link below."
}

Example curl Command

curl -X POST https://api.paylink.sa/api/merchants/{merchantId}/invoices/send \
-H "Content-Type: application/json" \
-H "X-API-KEY: your_api_key" \
-d '{
  "invoice": {
    "invoiceId": "unique_invoice_id"
  },
  "contacts": [
    {
      "type": "email",
      "contact": "[email protected]"
    },
    {
      "type": "sms",
      "contact": "966123456789"
    },
    {
      "type": "whatsapp",
      "contact": "966123456789"
    }
  ],
  "message": "Dear Customer, please find the invoice link below."
}'

Replace {merchantId} with the actual merchant ID and your_api_key with your actual API key in the headers.

Success Response

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

{
  "message": "Invoice link sent successfully"
}

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.
• Missing or Incorrect API Key: Verify that the X-API-KEY header is included and contains the correct API key.
• 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 can successfully send an invoice link using the API.