Payment sessions

Base URL: $CONSUMER_API

The object

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

List payment sessions for linked accounts

Logs

GET /payment-sessions

Pages the checkout sessions the caller started, across their tenants unless X-Tenant-ID selects one, with each session's status (for example pending, confirmed or failed). Pagination uses limit and after.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Payment sessions visible to the authenticated consumer

curl -X GET "$CONSUMER_API/payment-sessions" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Payment sessions visible to the authenticated consumer

Request provider-hosted checkout for a payable invoice

Logs

POST /payment-sessions

Returns provider-neutral next_action instructions; WSMS does not process payment instruments.

Body application/json

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

201 Payment session created with an external provider

Show 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

Errors 403

curl -X POST "$CONSUMER_API/payment-sessions" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
  "method": "method",
  "phone": "+258841234567",
  "return_url": "https://example.org/"
}'
Response 201
{
  "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/"
  }
}

Get payment-session status

Logs

GET /payment-sessions/{id}

Returns one checkout session the caller started, so a client can poll until it is confirmed or failed. Sessions started by someone else or outside the caller's scope return 404.

Parameters

idstring · path · required

Identifier of the payment session to return.

Returns

200 Payment session and provider-neutral status

Show 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
curl -X GET "$CONSUMER_API/payment-sessions/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "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/"
  }
}

Confirm a sandbox session

Logs

POST /payment-sessions/{id}/sandbox/confirm

Confirm a sandbox session (development only, 404 otherwise)

Development-only call that confirms one of the caller's own checkout sessions as if the provider had settled it, recording the payment, receipt and invoice allocation. It is available only when the sandbox payment provider is configured and returns 404 otherwise. Confirming an already confirmed session returns it unchanged.

Parameters

idstring · path · required

Resource identifier

Returns

200 Confirmed session

Show 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
curl -X POST "$CONSUMER_API/payment-sessions/{id}/sandbox/confirm" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "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/"
  }
}