SofizPay Logo

SofizPay

SofizPay Logo
SofizPay
Technical Documentation
Merchant Invoices API

Manage Invoices

Create and manage invoices using new items, existing items, or both. Update invoice status and manage items dynamically.

API Endpoints

POSThttps://sofizpay.com/merchant/invoices/create/

Create a new invoice using new items, existing items, or both

POSThttps://sofizpay.com/merchant/invoices/update/

Update an existing invoice, add/remove items, change status

GEThttps://sofizpay.com/merchant/invoices/

Get invoices for a merchant with optional filtering and pagination

Select Method

All endpoints require Sofizpay authentication using encrypted_sk parameter

Request Parameters (POST)

ParameterTypeRequiredDescription
encrypted_skstringYesEncrypted Sofizpay secret key for authentication
amountnumberYesTotal invoice amount
itemsarrayNoArray of new items to add to invoice
existing_item_idsarrayNoArray of existing item IDs with quantities
statusstringNoInvoice status (PENDING, PAID, CANCELLED)

Example Request

cURL

bash
1curl -X POST "https://sofizpay.com/merchant/invoices/create/" \
2  -H "Content-Type: application/json" \
3  -d '{
4  "encrypted_sk": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUF4...",
5  "amount": 1970,
6  "items": [
7    {
8      "description": "Custom laptop configuration service",
9      "quantity": 1,
10      "unit_price": 150
11    },
12    {
13      "description": "Extended warranty (2 years)",
14      "quantity": 1,
15      "unit_price": 220
16    }
17  ],
18  "existing_item_ids": [
19    {
20      "item_id": "item_001",
21      "quantity": 1
22    },
23    {
24      "item_id": "item_002",
25      "quantity": 1
26    }
27  ]
28}'

Python

python
1import requests
2import json
3
4url = "https://sofizpay.com/merchant/invoices/create/"
5data = {
6  "encrypted_sk": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUF4...",
7  "amount": 1970,
8  "items": [
9    {
10      "description": "Custom laptop configuration service",
11      "quantity": 1,
12      "unit_price": 150
13    },
14    {
15      "description": "Extended warranty (2 years)",
16      "quantity": 1,
17      "unit_price": 220
18    }
19  ],
20  "existing_item_ids": [
21    {
22      "item_id": "item_001",
23      "quantity": 1
24    },
25    {
26      "item_id": "item_002",
27      "quantity": 1
28    }
29  ]
30}
31
32response = requests.post(url, json=data)
33print(response.json())

JavaScript

javascript
1const response = await fetch('https://sofizpay.com/merchant/invoices/create/', {
2  method: 'POST',
3  headers: {
4    'Content-Type': 'application/json',
5  },
6  body: JSON.stringify({
7  "encrypted_sk": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUF4...",
8  "amount": 1970,
9  "items": [
10    {
11      "description": "Custom laptop configuration service",
12      "quantity": 1,
13      "unit_price": 150
14    },
15    {
16      "description": "Extended warranty (2 years)",
17      "quantity": 1,
18      "unit_price": 220
19    }
20  ],
21  "existing_item_ids": [
22    {
23      "item_id": "item_001",
24      "quantity": 1
25    },
26    {
27      "item_id": "item_002",
28      "quantity": 1
29    }
30  ]
31})
32});
33
34const result = await response.json();
35console.log(result);

Success Response (200)

Invoice created successfully with all items and details

json
1{
2  "success": true,
3  "message": "Invoice created successfully",
4  "invoice": {
5    "id": "inv_67890",
6    "amount": 1970.00,
7    "status": "PENDING",
8    "created_at": "2025-08-03T12:00:00Z",
9    "updated_at": "2025-08-03T12:00:00Z",
10    "items": [
11      {
12        "id": "invoice_item_001",
13        "description": "Custom laptop configuration service",
14        "quantity": 1,
15        "unit_price": 150.00,
16        "total_price": 150.00
17      },
18      {
19        "id": "invoice_item_002",
20        "description": "Extended warranty (2 years)",
21        "quantity": 1,
22        "unit_price": 220.00,
23        "total_price": 220.00
24      },
25      {
26        "id": "invoice_item_003",
27        "item_id": "item_001",
28        "name": "Samsung Galaxy S24 Ultra",
29        "quantity": 1,
30        "unit_price": 950.00,
31        "total_price": 950.00
32      },
33      {
34        "id": "invoice_item_004",
35        "item_id": "item_002",
36        "name": "MacBook Pro M3",
37        "quantity": 1,
38        "unit_price": 650.00,
39        "total_price": 650.00
40      }
41    ],
42    "total_items": 4,
43    "subtotal": 1970.00
44  }
45}

Error Response (400/404)

Common error responses for authentication or validation failures

json
{
  "error": "Invalid secret key"
}

Update Invoice Example (POST)

Update an existing invoice by adding items, removing items, or changing item details

json
1{
2  "encrypted_sk": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K...",
3  "invoice_id": "inv_67890",
4  "amount": 2195.00,
5  "status": "PAID",
6  "items_to_add": [
7    {
8      "description": "Express shipping",
9      "quantity": 1,
10      "unit_price": 25.00
11    }
12  ],
13  "items_to_remove": ["invoice_item_001"],
14  "items_to_update": [
15    {
16      "item_id": "invoice_item_003",
17      "quantity": 2,
18      "unit_price": 900.00
19    }
20  ]
21}

Security Note

Always keep your encrypted secret key secure. Use HTTPS for all API calls and validate all responses on your server.