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
- description (string): Description of the item. Example:
- 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"
- customerName (string): Name of the customer. Example:
- invoiceId (string): The unique identifier for the invoice. Example:
- 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"
- type (string): The type of contact, either
- 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
Commandcurl -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.
Updated about 2 months ago