Simulate a payment

Pay a sandbox link.

POSTCopy URL: https://api.avvio.xyz/business/api/v1/checkout/organizations/{orgId}/links/{linkId}/payments/simulate

POST/checkout/organizations/{orgId}/links/{linkId}/payments/simulate

Open in explorer

curl

IDEMPOTENCY_KEY=$(uuidgen)  # new key per call; reuse it only to retry this exact request
curl -s -X POST "$AVVIO_BASE_URL/checkout/organizations/$AVVIO_ORG_ID/links/$linkId/payments/simulate" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "reference": "order_1042",
        "clientReferenceId": "order_1042"
      }'

Node

const linkId = '<linkId>';
const idempotencyKey = crypto.randomUUID(); // new key per call; reuse it only to retry this exact request

const res = await fetch(`${process.env.AVVIO_BASE_URL}/checkout/organizations/${process.env.AVVIO_ORG_ID}/links/${linkId}/payments/simulate`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
    'Idempotency-Key': idempotencyKey,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    "reference": "order_1042",
    "clientReferenceId": "order_1042"
  }),
});
console.log(res.status, await res.json());

Python

import os
import uuid
import requests

linkId = "<linkId>"
idempotency_key = str(uuid.uuid4())  # new key per call; reuse it only to retry this exact request

res = requests.post(
    f"{os.environ['AVVIO_BASE_URL']}/checkout/organizations/{os.environ['AVVIO_ORG_ID']}/links/{linkId}/payments/simulate",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
        "Idempotency-Key": idempotency_key,
    },
    json={
        "reference": "order_1042",
        "clientReferenceId": "order_1042"
    },
)
print(res.status_code, res.json())

Try it

200OKResponse status200 OK400 Bad Request401 Unauthorized403 Forbidden404 Not Found409 Conflict429 Too Many Requests

{
  "id": "cmf9x1b2c0003q8b7h6j8k0lm",
  "status": "paid"
}

Path parameters

• orgIdstringRequired

  The opaque organization id issued to you, normally CUID-shaped (for example cmsx…). It is not an org_-prefixed alias. Pass it unchanged in every organization-scoped path.

• linkIdstringRequired

Headers

• Idempotency-KeystringRequired

  A unique value per logical operation, 1-255 chars of A-Z a-z 0-9 _ . : -.

  More

  Reuse it to retry. Same key with the same body replays the stored response; same key with a different body is a 409, because answering with the first call's result would hand you a receipt for a payout you did not request. A 4xx releases the key, so you can fix the body and reuse it.

  Reuse it; do not generate one per attempt. A key minted per attempt defeats replay entirely: every retry looks like a new request, so every retry pays. We also watch for an identical body arriving under a different key within 15 minutes and refuse it with DUPLICATE_REQUEST_DETECTED.

  Records are kept for 7 days. That is a retention window only: there is no path where an expired key is re-executed.

Body

This endpoint expects a JSON object, or no body.

• referencestringOptional

  Your own reference, and the deduplication key within this link. The same reference twice is one payment. Generated when omitted.

• clientReferenceIdstringOptional

  Echoed on the payment event exactly as a real card visit's ?client_reference_id= would be, so a fulfillment handler can be tested on its real join key.

Behavior

A buyer pays this link, in the sandbox. The one act the simulator cannot derive: everything afterwards follows from the link's amount and elapsed time, but whether somebody paid at all is a decision.

The amount picks the outcome. The last two digits of the link's total in minor units (the cents, on a two-decimal currency) select what happens, the same way the last four digits of a recipient account do on the payouts side. A total ending .04 is paid and then charged back a minute later, which is the case most integrations get wrong and the one thing no card processor's own sandbox can rehearse. Read GET /checkout/organizations/{orgId}/sandbox/scenarios for the table rather than hardcoding it.

Returns the payment as it stands the instant it was created. An ordinary amount is already paid; .02 comes back pending and settles over the next twenty seconds. Poll GET /links/{linkId}/payments, or subscribe to checkout_payment.*. Sandbox deliveries are signed identically to live ones and carry livemode: false.

Idempotency-Key is required, as it is on every other write here. Retrying with the same key returns the original payment rather than inventing a second buyer. Pass reference to choose the deduplication key yourself.

Responses

200The payment, as it stands at this instant.

Body

• idstringRequired
• statusstringRequired

  paid is not final: refunded and reversed (a chargeback) can follow, weeks later. pending on a bank payment that has settled means it is held (short of the total, or in the wrong currency) and reviewReason says why; it moves when someone accepts it in the dashboard.

  Allowed values:pendingprocessingpaidfailed

  Show 2 more values

  reversedrefunded

Errors

• 400

  LIVE_MODE_UNSUPPORTED: a live key on a sandbox-only operation. These manufacture payments and the events that follow them, so they are refused a live credential whatever organization the path names. Use an avvio_test_* key.

  Also BAD_REQUEST when the link cannot take a payment (a draft, a paused or expired link, or one that has already taken the maximum number of simulated payments), LINK_EXPIRED, VALIDATION_ERROR, IDEMPOTENCY_KEY_REQUIRED and IDEMPOTENCY_KEY_INVALID.

• 401

  The key was refused. Nothing ran.

  • UNAUTHORIZED: missing, invalid or revoked, or a key on a route that does not accept one.
  • KEY_EXPIRED: the key passed the expiry it was issued with. Issue a new one; an expired key cannot be rotated.
  • KEY_IP_NOT_ALLOWED: the key is pinned to source addresses and this request came from another.
• 403

  A valid key that may not make this write. Nothing was changed.

  • FORBIDDEN: the key belongs to a different organization, or your business has not completed verification to accept payments; detail says which.
  • ACCOUNT_BLOCKED: API access for your organization is suspended.
  • LIVE_KEY_ORG_NOT_APPROVED: a live key, before we have approved your business verification. Use a test key until then.
  • INSUFFICIENT_SCOPE: a read-only key.
• 404

  No such link or product in this organization, or the id belongs to another one.

• 409

  Either the key was reused with a different body (IDEMPOTENCY_KEY_CONFLICT: use a new key), or the first request with this key is still running (IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS: back off and retry the same key).

• 429

  Too many requests. The default ceiling is 100 requests per minute per API credential on a 60-second window. High-volume payout and reconciliation routes declare a 600/minute override, and batch submission a 30/minute ceiling. A separate 2,000/minute per-source-IP abuse ceiling always applies.

  Obey Retry-After; it is in seconds and is authoritative. A 429 means the request was refused before the handler ran. Retry reads normally; retry an idempotent mutation with its same Idempotency-Key.

Error body · Error

• typestringRequired

  Stable machine-readable code.

• detailstringRequired

  What went wrong, in a sentence. Always a string, so detail.toLowerCase() is safe.

  More

  This is the field to read on BAD_REQUEST and PROVIDER_REJECTED, where the type alone does not name the condition.

• messagestringRequired

  The same text as detail, kept for integrations written before detail existed. Read detail.

• resolutionstringOptional

  What to do about it, when there is a specific answer. It is not on every error (it is absent on BAD_REQUEST, NOT_FOUND, PAYOUT_NOT_CANCELABLE and DESTINATION_ACCOUNT_NOT_FOUND), so treat it as optional and fall back to detail.

• statusintegerRequired

  HTTP status, repeated in the body.

• statusCodeintegerRequired

  The same value as status, kept for integrations written before status existed. Read status.

• requestIdstringRequired

  Quote this to support and we can find the exact request. Also sent as the x-request-id response header, which is the only place it appears on a successful response. Success bodies do not carry it. Send your own x-request-id on the request and we use it, so your trace and ours share one identifier; otherwise we mint one.

• errorsarray of stringOptional

  Present on VALIDATION_ERROR; names each field that failed.

• originalIdempotencyKeystringOptional

  On DUPLICATE_REQUEST_DETECTED only. Send the request again with this to receive the original payout instead of making a second one. Without it there is no way to recover except by risking a double payment.

• originalPayoutIdstringOptional

  On DUPLICATE_REQUEST_DETECTED only. The payout the first request created.

• originalBatchIdstringOptional

  On a batch DUPLICATE_REQUEST_DETECTED. The run the first request created.

• originalRequestIdstringOptional

  On a 409 PAYOUT_OUTCOME_UNKNOWN replay. The requestId of the call whose outcome is unknown; quote it to support.

• existingRecipientIdstringOptional

  On BANK_ACCOUNT_ALREADY_LINKED. The recipient in your organization that already holds this account.

• existingMethodIdstringOptional

  On BANK_ACCOUNT_ALREADY_LINKED. The payment method on that recipient.

Branch on type, never on the status or the message. Every error type is listed with what to do about it.

Avvio Checkout · Sandbox · operation simulateCheckoutPayment

Try it: Simulate a payment

POST https://api.avvio.xyz/business/api/v1/checkout/organizations/{orgId}/links/{linkId}/payments/simulate

API key Required

Test keys only. Sent as x-api-key through this site's proxy to the Avvio API, never saved, and cleared when you close this dialog.

orgId pathRequired

linkId pathRequired

Idempotency-Key headerRequired

Body JSON{ "reference": "order_1042", "clientReferenceId": "order_1042" }

Send request