Simulate a payment outcome

Force an outcome on a sandbox payment.

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

POST/checkout/organizations/{orgId}/payments/{paymentId}/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/payments/$paymentId/simulate" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "action": "chargeback"
      }'

Node

const paymentId = '<paymentId>';
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}/payments/${paymentId}/simulate`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
    'Idempotency-Key': idempotencyKey,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    "action": "chargeback"
  }),
});
console.log(res.status, await res.json());

Python

import os
import uuid
import requests

paymentId = "<paymentId>"
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']}/payments/{paymentId}/simulate",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
        "Idempotency-Key": idempotency_key,
    },
    json={
        "action": "chargeback"
    },
)
print(res.status_code, res.json())

Try it

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

{
  "id": "cmf9x1b2c0003q8b7h6j8k0lm",
  "status": "reversed",
  "moved": true
}

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.

• paymentIdstringRequired

  The payment id, or the reference you created it with. A reference used on more than one of your links is ambiguous and answers 409; pass the id instead.

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.

• actionstringRequired
  Allowed values:refundchargebackfail

Behavior

Move a simulated payment now, instead of waiting out its timeline. A test suite cannot sit for sixty seconds waiting for a chargeback, and a chargeback is the outcome worth rehearsing most.

chargeback is checkout_payment.reversed: money taken back after you booked it. refund is a full refund. fail declines a payment still in flight.

Safe alongside the timeline: both go through the same status-guarded transition, so forcing a chargeback and then letting the timeline run delivers exactly one checkout_payment.reversed. moved is false when the transition was refused (a terminal payment, or somebody got there first). That is normal and not an error.

Responses

200Where the payment stands, and whether this call moved it.

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
• movedbooleanRequired

  False when the transition was refused. Not an error.

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 simulateCheckoutPaymentOutcome

Try it: Simulate a payment outcome

POST https://api.avvio.xyz/business/api/v1/checkout/organizations/{orgId}/payments/{paymentId}/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

paymentId pathRequired

Idempotency-Key headerRequired

Body JSON{ "action": "chargeback" }

Send request