Settlement

Beta FeatureThe Transaction Simulations feature is currently in beta. API endpoints and behavior may change as we continue to refine the product. 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.

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	No	The settlement amount in cents (merchant currency). If omitted, settles for the original authorization amount.

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 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.
`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
  }'

Introduction

Plan & Set Up Your Program

Build Your Program

Run Your Program

Rewards

Embedded Wallets

Endpoint

Path parameters

Headers

Body

Response

Errors

Behavior notes

Example

​Endpoint

​Path parameters

​Headers

​Body

​Response

​Errors

​Behavior notes

​Example

Endpoint

Path parameters

Headers

Body

Response

Errors

Behavior notes

Example