Payment baskets

Base URL: $CONSUMER_API

The object

invoice_idstring · required

The invoice this result is for.

sessionobject · optional
Show child attributes
idstring · required
tenant_idstring · required
invoice_idstring · required
amountinteger (int64) · required
currencystring · required
statusstring · required

one of pending, confirmed, failed, expired, cancelled

next_actionunion · required
errorstring · optional

Present instead of session when a payment could not be started for this invoice. The text is generic and does not say why.

The object
{
  "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."
}

Start payments for several invoices at once

Logs

POST /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-Keystring · header · optional

Optional 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

itemsarray of CreatePaymentSession · required

One 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_idstring · required
methodstring · required

A 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.

phonestring · optional

Required when the chosen checkout method has requires_phone set.

return_urlstring (uri) · optional

Returns

200 One result per invoice, each with a session or an error

Show attributes
dataarray of ConsumerPaymentBasketItem · required

One result per requested invoice, in request order.

Show child attributes
invoice_idstring · required

The invoice this result is for.

sessionobject · optional
Show child attributes
idstring · required
tenant_idstring · required
invoice_idstring · required
amountinteger (int64) · required
currencystring · required
statusstring · required

one of pending, confirmed, failed, expired, cancelled

next_actionunion · required
errorstring · optional

Present instead of session when a payment could not be started for this invoice. The text is generic and does not say why.

Errors 400 · 401

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/"
    }
  ]
}'
Response 200
{
  "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."
    }
  ]
}