Start payments for several invoices at once
LogsPOST /payment-baskets
Starts one payment session per invoice, for 1 to 20 invoices that may belong to different utilities, and returns one result per invoice in request order. Each invoice is checked on its own exactly as when starting a single payment session: it must be on an account where the caller holds the payment.create account permission, have an outstanding balance, and use a payment method the utility currently accepts (with a phone number where the method needs one), and the utility's payments capability must be active. An invoice that fails any check gets a generic error in its result instead of a session, and the rest still proceed, so the response is 200 even when every item fails. An empty basket, more than 20 items, a missing or repeated invoice_id, or an unknown body field returns 400 before any session starts. With an Idempotency-Key header each item is made retry-safe under the key plus its invoice ID.
Parameters
Idempotency-KeyOptional retry key. Each item's session is created under this key joined with the item's invoice ID, so repeating the same basket returns the sessions already started.
Body application/json
itemsOne entry per invoice to pay, 1 to 20 entries, each with a distinct invoice_id. Invoices may belong to different utilities.
Show child attributes
invoice_idmethodA checkout method code, as listed in the utility's checkout_methods in the consumer payment availability. The codes come from the utility's payment connectors; the server keeps no list of providers and refuses a method no live connector offers.
phoneRequired when the chosen checkout method has requires_phone set.
return_url
Returns
200 One result per invoice, each with a session or an error
Show attributes
dataOne result per requested invoice, in request order.
Show child attributes
invoice_idThe invoice this result is for.
sessionShow child attributes
idtenant_idinvoice_idamountcurrencystatusone of
pending,confirmed,failed,expired,cancellednext_action
errorPresent instead of session when a payment could not be started for this invoice. The text is generic and does not say why.
curl -X POST "$CONSUMER_API/payment-baskets" \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
"method": "method",
"phone": "+258841234567",
"return_url": "https://example.org/"
}
]
}'
# No matching CLI command; use cURL or direct HTTP.
const res = await fetch("$CONSUMER_API/payment-baskets", {
method: "POST",
headers: {
Authorization: "Bearer sk_test_...",
"Content-Type": "application/json"
},
body: JSON.stringify({
"items": [
{
"invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
"method": "method",
"phone": "+258841234567",
"return_url": "https://example.org/"
}
]
})
});
const data = await res.json();
import requests
res = requests.post(
"$CONSUMER_API/payment-baskets",
headers={
"Authorization": "Bearer sk_test_..."
},
json={
"items": [
{
"invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
"method": "method",
"phone": "+258841234567",
"return_url": "https://example.org/"
}
]
}
)
data = res.json()
body := strings.NewReader(`{
"items": [
{
"invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
"method": "method",
"phone": "+258841234567",
"return_url": "https://example.org/"
}
]
}`)
req, _ := http.NewRequest("POST", "$CONSUMER_API/payment-baskets", body)
req.Header.Set("Authorization", "Bearer sk_test_...")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
{
"data": [
{
"invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
"session": {
"id": "pay_2DxUipfYyfRuqNn2cZf00RTYqB3",
"tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
"invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
"amount": 125000,
"currency": "MZN",
"status": "pending",
"next_action": {
"type": "redirect",
"url": "https://example.org/"
}
},
"error": "Payment could not be started."
}
]
}