Getting started

Authentication & requests

Every call carries your API key, sends a JSON body, and gets a JSON answer with a status code you can rely on.

API keys

HTTP header

Authorization: Bearer YOUR_API_KEY

Sign in to the merchant portal as an account administrator.
Open Settings → API Credentials and create a key.
Copy it straight into your secrets store. Cashwo keeps only a hash of the key, so it can't be shown again; if it's lost, revoke it and create a new one.

Keep the key on your server.Never put it in a mobile app, browser code or a public repository. Anyone holding it can create and cancel agreements in your name. If a key leaks, revoke it in the portal straight away.

Requests

Send POST requests with Content-Type: application/json. The body is a JSON object whose action names the operation:

Action	What it does
`create_agreement`	Create a PayTo agreement and get the link for your customer.
`get_agreement`	Read one agreement.
`list_agreements`	Search and page through agreements.
`cancel_agreement`, `suspend_agreement`, `resume_agreement`	Change an agreement's status.
`get_payment`	Read one payment.
`list_payments`	Search and page through payments.

Responses

Every response has success. A failure also has error (a message, or a list when validation fails) and an error_code your code can branch on.

422 Unprocessable Entity

{
  "success": false,
  "error_code": "validation_failed",
  "error": ["Invalid Email.", "amount must be greater than 0."]
}

HTTP	Meaning
`200`	OK.
`201`	Agreement created.
`202`	Sent to the customer's bank; it completes when the bank confirms.
`400`	The body isn't a JSON object, or the action is unknown.
`401` / `403`	Missing or wrong API key / merchant account not active.
`404`	No such agreement or payment in your account.
`409`	Conflict, such as a status change that isn't allowed.
`422`	Validation failed.
`5xx`	A problem at Cashwo or the payment network. Retry with the same Idempotency-Key.

The full list is on the Errors page.

Safe retries with Idempotency-Key

Send an Idempotency-Key header with every create_agreement, cancel_agreement, suspend_agreement and resume_agreement call. Use a value that's unique to the operation in your system, such as your invoice ID.

HTTP header

Idempotency-Key: invoice-10482-create

If a call times out, send it again with the same key and body. Cashwo returns the first response instead of doing the work twice, and adds an Idempotent-Replayed: true header.
The same key with a different body is refused with 409 idempotency_key_reused.
If the first request is still running, a retry gets 409 idempotency_in_progress. Wait a moment and retry.
Keys last 24 hours, are 1–100 characters (letters, digits, - _ : .) and are scoped to your account. A 5xx answer isn't stored, so you can retry it with the same key.
If your HTTP client can't set headers, send "idempotency_key" in the JSON body instead.

Pagination

List actions return results newest first. Send limit (1–100, default 25); the response has has_more and next_starting_after. Pass next_starting_after back as starting_after until has_more is false.

Response shape

{
  "success": true,
  "agreements": [ … ],
  "has_more": true,
  "next_starting_after": 4101
}