Browse the docs

Simulate card transaction (non-prod)

POST /v1/api-gateway/card/{card_id}/transactions

Sandbox/testing only: runs a card transaction (AUTHORIZATION, REVERSAL, CLEARING, WITHDRAWAL or REFUND) through the same processing path as a real one, including webhooks. A declined simulation still returns 200 with success: false and the decline reason in message. In production these routes return 403 DEV_ONLY_ENDPOINT. Not to be confused with GET card/{card_id}/transactions, which lists real transactions.

Request

Authentication: your API key in the x-api-key header.

Path parameters

Field	Type	Description
`card_id` required	string, uuid	Card id.

Headers

Field	Type	Description
`Idempotency-Key`	string	A unique string you choose, up to 255 characters, that makes this request safe to retry. If a request times out or fails in transit, send it again with the same key: the status code and body of the first attempt are returned and the operation is not performed a second time. Stored replies — including failures — are replayed for 24 hours, after which the same key starts a fresh request. Reusing a key for a different request, or sending it while the first request is still running, returns 409. Omit the header and the request behaves exactly as before. Document upload endpoints do not accept it.

Body

Field	Type	Description
`transaction_amount` required	number	Transaction amount in `transaction_currency`, major units (e.g. `12.34`).
`transaction_currency` required	string	ISO-4217 code of the transaction currency, e.g. `USD`. Converted to the card currency at the current rate.
`transaction_type` required	string	Card network event to simulate: `AUTHORIZATION` (hold), `CLEARING` (settle a hold), `REVERSAL` (release a hold), `REFUND` (credit back), `WITHDRAWAL`. `CLEARING`, `REVERSAL` and `REFUND` reference an earlier event via `original_transaction_id`.One of: `AUTHORIZATION`, `REVERSAL`, `CLEARING`, `WITHDRAWAL`, `REFUND`
`original_transaction_id`	string	`transaction_id` of the earlier simulated event this one applies to (required for `CLEARING`, `REVERSAL`, `REFUND`).
`merchant_name`	string	Merchant name shown on the transaction.
`merchant_country_code`	string	ISO-3166 alpha-2 country of the merchant, e.g. `US`.

Example request

cURL

curl --request POST \
     --url 'https://api.themooncard.com/v1/api-gateway/card/8d2cd518-5ef2-4280-91e8-63b1a0e672e7/transactions' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "transaction_amount": 12.34,
       "transaction_currency": "USD",
       "transaction_type": "AUTHORIZATION",
       "original_transaction_id": "string",
       "merchant_name": "string",
       "merchant_country_code": "string"
     }'

Responses

200 Success

Field	Type	Description
`success` required	boolean	`true` when the simulated transaction was approved; `false` when it was declined (still HTTP 200).
`message` required	string	"<Transaction\|Reversal\|Clearing\|Withdrawal\|Refund> simulated successfully", or "<Type> declined: <reason>".
`transaction_id` required	string	Id of the simulated transaction (uuid).

JSON

{
  "success": true,
  "message": "Transaction simulated successfully",
  "transaction_id": "2f1a6b3c-4d5e-4f60-8a7b-9c0d1e2f3a4b"
}

400 Error

Validation failed (errors[] lists each offending field) or a domain rule rejected the request ({ message, code }).