Settlement

Simulate settling an open authorization to test merchant fund capture flows.

Simulation endpoints are available in development environments only — production returns 404 Not Found.

Simulate settling an open authorization — for example, when a merchant captures funds after the customer has left. This converts the authorization hold into a posted transaction.

Use this to test how your integration handles the transition from authorization to settlement, including the transaction.spend.completed webhook.

Endpoint

POST /v1/simulate/transactions/:transactionId/settle

Path parameters

Parameter	Type	Required	Description
transactionId	string (UUID)	Yes	The ID of an existing authorized transaction to settle. Must belong to your tenant or one of its subtenants.

Headers

Header	Type	Required	Description
Api-Key	string	Yes	Your tenant API key. The tenant scope is resolved from this key.
Content-Type	application/json	Yes	—

Body

Field	Type	Required	Description
amount	integer	Yes	The settlement amount in cents (merchant currency). To settle for the full authorization, pass the authorized amount. Must be between 1 and 2147483647. Unknown fields return 400.

Example request

{
  "amount": 5000
}

Response

A successful response returns the transaction ID and settled status.

200 OK

{
  "transactionId": "f3a1c92e-1b3d-4d1e-bb22-12c0a4d5b8f9",
  "status": "settled",
  "completionReason": "settlement"
}

Field	Type	Description
transactionId	string (UUID)	The transaction ID.
status	string	The transaction status: settled.
completionReason	string	The completion type: settlement.

Errors

Status	When
400 Bad Request	Transaction is not a card authorization, transaction is already settled, transaction is already closed, no card associated with the transaction, or the card has no processor ID.
404 Not Found	Endpoint not available in production, simulations are not enabled for your tenant, or the transaction does not exist.
422 Unprocessable Entity	The simulated settlement was not processed, so no settlement was recorded.
500 Internal Server Error	Invalid currency or unhandled error during simulation.

Behavior notes

• Transaction must be an open authorization. You can only settle authorizations that have not yet settled or closed.
• FX conversion applies. The settlement amount is converted using the transaction’s original merchant and billing currencies.
• Triggers webhooks. The settlement fires the same webhooks as a real settlement, including transaction.spend.completed.

Example

curl -X POST https://api-dev.rain.xyz/v1/simulate/transactions/f3a1c92e-1b3d-4d1e-bb22-12c0a4d5b8f9/settle \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000
  }'