Skip to main content
FluxanDeveloper docs
简体中文

Testing guide

Learn how the test and live environments are isolated and how to test checkout, refunds, webhooks and idempotency, with a 33-item self-test checklist.

Last updated 2026-11-13 · API contract v1.0.0

Test environment overview

ItemTest environment (test)Live environment (live)
API addresshttps://api.fluxan.example (same as live)Same
What determines the environmentTest API keyLive API key
Key prefixsk_test_sk_live_
Data you can accessTest objects only; retrieving a live object returns 404Live objects only
ProviderThe platform's built-in simulated provider; nothing external is contactedThe live provider account
CardsTest cards only: one generic test card, whose values you can see after signing in to the merchant portal. You choose the result on the simulated payment page; the card number and amount don't decide itReal cards
FundsNo real fundsReal charges, settlements and payouts
WebhooksA separate endpoint and signing secret for the test environmentLive endpoint and signing secret
Pricing0 (no fees are charged) unless test rates are configured separately. To rehearse billing, contact the platform to configure test ratesLive rates configured under your contract
RefundsSubmitted to the provider as soon as they're created, with no platform review, and the simulated provider marks them succeeded right away. If your funds fall short, create returns 422Submitted to the provider as soon as they're created, with no platform review. If your funds fall short, create returns 422
Settlement and payoutsSettlements are generated under test settlement terms (if not configured separately: T+1 calendar day, daily settlement, settlement fee 0). The platform rehearses payout confirmation and the payout. No real payout happens, and your payout account isn't usedReal
Merchant portal indicatorOrange "Test" badge and bannerGreen "Live" badge
When it's availableAfter merchant onboardingAfter the platform completes the onboarding checks and activates the live environment
DisbursementsThe platform enables the disbursement capability separately for the test environment and sets up the PKR channel and limits. No real funds move. Payee details are validated the same way as in live. An accepted disbursement stays processing until you choose Simulate result on its details page in the merchant portal: success or failure, and for a succeeded one, a reversal. Unknown outcomes can't be simulatedThe platform enables it separately for the live environment. Real money is paid out and can't be recalled
  • Retrieving a live object with a test key returns 404. A live key can't send transactions to the test provider.
  • Test data isn't deleted after the live environment is disabled. Test objects can only be retrieved in the test environment.
  • How to test disbursements, the self-test table T1 to T11 (including reversals), and how to test unknown outcomes are in Disbursements. The merchant self-test checklist on this page doesn't cover disbursements. In the test environment, settleable funds also come from PKR test payments, which become settleable only after the test environment's lock period. A PKR disbursement amount must be whole rupees (amount a multiple of 100) in both environments, or you get 400 invalid_request.

How the simulated provider gives results

The test environment is answered by the platform's built-in simulated provider. It doesn't contact any real provider, and you choose the results:

  • Payments: every test payment, through the direct API or hosted checkout, first returns requires_action. The payer goes to the simulated payment page (with the direct API, you redirect them to next_action.url; at checkout, they land there after submitting) and chooses Simulate success or Simulate failure. Until a choice is made, the payment stays requires_action, and in the meantime you can also give the result with Simulate result on the payment's details page in the merchant portal, picking a failure reason code for a failure. A payment nobody chooses for is closed as abandoned after 60 minutes, and a closed payment can't be simulated as succeeded any more. Wallets and other non-card payments go to the simulated payment page too, Cash App at checkout included; a simulated failure there has the reason processing_error. Direct wallet is the exception: it has no simulated payment page, so the payment stays requires_action after you create it and you choose success or failure with Simulate result on the order details page. If you don't pick a failure reason it's processing_error, and authentication_expired simulates a payer who never confirms. A payment with no result chosen goes to manual follow-up after 24 hours.
  • Refunds: the simulated provider marks a refund succeeded as soon as it's created, and you receive refund.succeeded.
  • Disbursements: an accepted disbursement stays processing until you choose success or failure with Simulate result on its details page in the merchant portal. A succeeded disbursement can also be simulated as reversed (disbursement.reversed).
  • Webhooks: in the test environment you can Resend real events from the merchant portal to rehearse duplicate deliveries. See Resend events in the test environment for the rules.

Simulated results are booked, charged and pushed as webhooks exactly like real provider results, so you can rehearse the webhook, refund and settlement flows end to end as in live. The simulated provider doesn't inject faults, doesn't send provider callbacks and has no real 3DS. Scenarios it can't produce are marked "simulation not supported yet" in Test cards and scenarios, with a way to test them yourself.

Note: Do disbursements stay processing in the test environment?

An accepted test disbursement stays processing until you choose success or failure with Simulate result on its details page in the merchant portal; for a succeeded one you can also choose a reversal. Only your choice decides the result, not the amount or the account. See Disbursements.

Warning

Use test cards only: the test environment has a single generic test card, whose values you can see after signing in to the merchant portal. The simulated provider doesn't charge anything, but real card numbers still must not enter the test environment. Never use or share real card data in the test environment, support tickets, chats or screenshots. No real funds move in the test environment.

Prerequisites

  1. A test API key with the scopes you need: Create a test key (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer).
  2. A webhook endpoint and signing secret for the test environment: Configure webhooks (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer).
  3. Registered redirect URLs (you can register http://localhost in the test environment): Redirect URLs (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer).
  4. A publicly reachable HTTPS test URL: use a public test endpoint or a controlled tunnel to expose your local service. The platform never connects to internal-network or local addresses.

Test cards and scenarios

The placeholders in the table are scenario identifiers. Every card scenario in the test environment uses the same generic test card (placeholder <TEST_CARD>). The merchant portal shows its card number, expiry rules and CVC only after you sign in (View test card values (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)). These public docs don't publish any test card values. The "Other input" column says how to get each result in the test environment: which result to choose on the simulated payment page, or which failure reason code to pick under Simulate result on the payment's details page.

#ScenarioScenario identifierOther inputExpected API resultExpected eventsAcceptance criteria
C1Succeeds directly (no 3DS needed)<TEST_CARD>View in the merchant portal (sign-in required) (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)Any future expiry date and any 3-digit CVC; choose "Simulate success" on the simulated payment page201 requires_action → succeeded after the choice, captured_amount = amount (every test payment goes to the simulated payment page first and never returns succeeded straight away)payment.requires_action, payment.succeededAC-008, AC-010
C23DS frictionless pass (can't be simulated yet)— (simulation not supported yet)The test environment has no real 3DSLive behavior: 201 succeeded, possibly without going through requires_actionpayment.succeeded (there may be no payment.requires_action)AC-008
C3Succeeds after a 3DS challenge<TEST_CARD>View in the merchant portal (sign-in required) (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)Send the payer to the platform page at next_action.url. In the test environment it's the simulated payment page: choose "Simulate success" (in live, it's the issuer challenge)201 requires_action → succeeded after the choicepayment.requires_action, payment.succeededAC-009, AC-011
C43DS authentication failed<TEST_CARD>View in the merchant portal (sign-in required) (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)While the payment waits on the simulated payment page, use "Simulate result" on the payment's details page to choose failure with reason code authentication_failedrequires_action → failed (authentication_failed)payment.failed—
C53DS succeeded but declined by issuer (can't be simulated yet)— (simulation not supported yet)The test environment has no real 3DSLive behavior: requires_action → failed (card_declined), with a successful authentication resultpayment.failedAC-012
C6Declined by issuer<TEST_CARD>View in the merchant portal (sign-in required) (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)Choose "Simulate failure" on the simulated payment pagerequires_action → failed (card_declined)payment.failed—
C7Succeeds with another card after a decline<TEST_CARD>View in the merchant portal (sign-in required) (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)Do C6 first, then confirm with a new idempotency key and choose success on the simulated payment page the second timeSame Payment, attempt_count=2, succeededpayment.failed, payment.succeeded (version increases)AC-026
C8Incorrect card details<TEST_CARD>View in the merchant portal (sign-in required) (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)While the payment waits on the simulated payment page, use "Simulate result" on the payment's details page to choose failure with reason code incorrect_card_datarequires_action → failed (incorrect_card_data)payment.failed—
C9Succeeds after a timeout / outcome unknown (simulation not supported yet)— (simulation not supported yet)See the note below the table for how to self-testLive behavior: 202 processing + needs_query → succeeded laterpayment.succeededAC-019
C10Fails after a timeout / outcome unknown (simulation not supported yet)— (simulation not supported yet)See the note below the table for how to self-testLive behavior: 202 processing → failed laterpayment.failed—
C11Duplicate provider callback (simulation not supported yet)— (simulation not supported yet)See the note below the table for how to self-testLive behavior: succeededOnly one payment.succeeded event ID (it may be delivered more than once)AC-021 (merchant-side counterpart)
C12Card brand not supported (can't be simulated yet)— (simulation not supported yet)The test environment has a single generic test cardLive behavior: 422 card_brand_not_supportedNone—
C13Refund will fail (can't be simulated yet)— (simulation not supported yet)Refunds on the simulated provider succeed immediatelyLive behavior: payment succeeded; refund processing → failedrefund.failed—

Note: Scenarios that can't be simulated yet

The simulated provider doesn't inject faults, doesn't send provider callbacks and has no real 3DS. There's only one generic test card, and refunds succeed right away. So these scenarios can't be simulated yet. To self-test:

  1. Outcome unknown (C9, C10): use a unit test or a mock service to feed your code the 202 processing + needs_query response (the processingNeedsQuery example in Create payment). Confirm that it shows "Confirming", doesn't charge again, and then handles the result through a query or an event. Next, set the client timeout to 100 ms and make a C1 payment, then retry with the same key or query by order ID. Confirm that you end up with only one payment.
  2. Duplicate callbacks (C11): use steps 6 (redelivery after a timeout) and 8 (Resend the same event in the merchant portal) of the webhook tests below to make the same event ID arrive again, and confirm that you process it only once. Use "Send test event" to check receipt, signature verification and archiving by event ID.
  3. C2, C5, C12, C13: the test environment can't produce these (no real 3DS, only one card, refunds succeed right away). Make your code handle the "Live behavior" shown in the table.

In the test environment, only the simulated payment page or Simulate result decides the result; no card number or amount triggers a scenario. A payment the payer never chooses for stays requires_action and is closed as abandoned after 60 minutes, and a closed payment can't be simulated as succeeded any more. Failure reason codes are defined in Payment failure reasons. You can see the status, attempts and events of every test payment on the Payments (opens the merchant portal in a new tab) (Test environment) page, and Simulate result is on the payment's details page.

Hosted checkout tests

ScenarioActionExpected resultAC
No 3DS requiredCreate a session → open checkout_url → pay with the test card and choose Simulate success on the simulated payment pageThe result page shows success and returns to return_url; both the payment query and the webhook show succeededAC-010
3DS requiredPay at checkout with the test card (in the test environment, the simulated payment page stands in for the 3DS challenge)After the payer completes the step on the platform page, they return to checkout; your server-side key never appears in the browserAC-011
Two tabs submit at the same timeOpen the same checkout_url in two tabs and click pay in both at the same timeOnly one in-flight attempt is createdAC-024
Session expiresCreate a session, do nothing, and wait past expires_atThe page no longer accepts new submissions; if a payment was already in flight, its outcome is still confirmedAC-025
Click "Return to merchant"Click "Return to merchant" on the checkout pageThe browser goes to cancel_url; your page queries the status first and doesn't mark the order "canceled" directly—
Create a session for a paid orderCreate a session again for an order that has already been paid200 + a read-only session with status=completed—
Cash AppAsk the platform to turn on the Cash App capability for the test environment, create a USD session, choose Cash App at checkout, submit, and pick the result on the simulated payment pageNo card or billing details needed; the result page, queries and webhooks behave as for a card payment, with card set to null—
USD and JPYCreate sessions for USD 10000 and JPY 10000Checkout shows USD 100.00 and JPY 10,000AC-028

Refund tests

Based on a successful payment of USD 10000:

ScenarioActionExpected resultAC
Partial refundRefund 4000201 processing (submitted to the provider immediately) → succeeded (the simulated provider marks it succeeded right away in the test environment); the payment's refund_status=partialAC-031
Multiple partial refundsRefund another 6000 (with a new merchant refund ID and idempotency key)Total 10000, refund_status=full, and the payment status is still succeededAC-031, AC-030
Full refundExplicitly pass an amount equal to the refundable amountAfter the refund succeeds, the original payment is still recorded as succeededAC-030
Exceeds the refundable principalAfter 4000 has been refunded, request 8000422 refund_amount_exceedsAC-032
Concurrent over-refundSubmit two refunds of 6000 at the same time (different merchant refund IDs)Only the one that fits within the limit is accepted; the other returns 422AC-032
Insufficient fundsAfter asking the platform to configure a non-zero test rate for you, refund the full amount right after the payment completes422 insufficient_refund_funds; the message gives the shortfall and no refund is createdAC-034
Duplicate merchant refund IDUse a new idempotency key with the same merchant_refund_noNo second refund is created (409 refund_no_conflict)—
Refund timeoutRetry with the same key after a client timeoutThe same refund is returned and no second refund is createdAC-033
Refund failureCan't be simulated yet (the simulated provider's refunds succeed right away); in live, this is the C13 scenarioLive behavior: refund.failed; the reserved funds are released—
Refund with a read-only keyCreate a refund with a key that has only refunds:read403 forbiddenAC-003

Caution: Refunds and funds in the test environment

  • The funds from a payment that has just completed are pending settlement. When the provider supports it, the platform can reserve the payment's own net amount that is pending settlement. The default test rate is 0, so a full refund usually doesn't run into a funds shortfall. When a non-zero test rate is configured, the original payment's fee isn't refunded by default, so a full refund falls short by one fee. For example, with a payment of 100.00 and a fee of 3.50, the shortfall is 3.50. This is correct behavior: either make a partial refund first, or contact the platform to record a top-up in the test environment and then resubmit with the same merchant refund ID and amount.
  • A refund is submitted to the provider as soon as it's created, so its status is processing right away. This works the same in test and live; in the test environment, the simulated provider then marks it succeeded right away and you receive refund.succeeded. The platform doesn't review refunds; insufficient funds are rejected at creation with 422 (see the previous point). pending_review is kept only for compatibility and is no longer produced.

Webhook tests

  1. Prepare a publicly reachable HTTPS test URL: use a public test endpoint or a controlled tunnel to expose your local service. The platform never connects to internal-network or local addresses.
  2. In the merchant portal (test environment), configure the endpoint (step-up verification required). The portal shows the test signing secret only once, when you create the endpoint. Write it to your test environment configuration right away (rotate it if you lose it).
  3. Click "Send test event". The delivery record shows success (2xx), and your logs show that signature verification passed and the event was archived by event ID. Test events carry X-Pay-Test-Event: true, are delivered only once without retries, and don't create real payments, refunds or ledger entries.
  4. Tampering test: use the webhook test vector to check your signature verification function. After you modify the request body, it must reject the request (AC-059).
  5. Retries after a failure: make the endpoint temporarily return 500, then complete a test payment with the test card (choose Simulate success on the simulated payment page) and watch the retries of that payment.succeeded event 1 minute and 5 minutes after the first delivery. The event ID stays the same, while the delivery ID and signature timestamp differ. After you restore the endpoint, return 2xx and confirm that the event is accepted and deduplicated (AC-060). Test events aren't retried, so this step uses a real test payment event.
  6. Deduplication after a timeout: make the endpoint wait 6 seconds before it returns 200 (more than 5 seconds). The platform treats the delivery as timed out and redelivers it. Confirm that your business logic runs only once.
  7. Out-of-order events: use the C7 scenario to watch the version of payment.failed and payment.succeeded, and confirm that your logic processes events by version.
  8. Final failure (optional; the full cycle takes about 48 hours): keep the endpoint failing. After 8 attempts, the event moves to the failed list and you receive an email notification. Backfill it with GET /v1/events/{event_id}, or resend it from the event deliveries page (the event ID doesn't change, so you can also verify that a duplicate delivery is processed only once, AC-061).
  9. Internal addresses: try to configure the endpoint as an internal-network or localhost address. It must be rejected (AC-062).

You can see delivery results under Event deliveries (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer).

Webhook failure and retry test
Webhook failure and retry test

Resend events in the test environment

In the test environment you can resend events yourself without contacting the platform: click Resend on an event in the event details on the event deliveries page, or in the notifications tab of a payment or disbursement details page.

  • The resend reuses the original event ID and payload and generates a new delivery ID and signature. It doesn't redo the payment or the bookkeeping. The delivery record shows the source as "Merchant resend".
  • You can resend a real event in any delivery status, including one that was already delivered. Test events sent with "Send test event" can't be resent.
  • The current environment must have an enabled endpoint. You can resend the same event once every 60 seconds and up to 50 times per hour; beyond that you get 429 with how long to wait.
  • The live environment doesn't offer self-service resends yet: for an event that finally failed, fix your endpoint and contact the platform to resend it, or backfill it with GET /v1/events/{event_id}.

Idempotency and error tests

ScenarioActionExpected resultAC
Sequential repeats with the same keyCreate a payment 10 times with the same keyThe same payment, charged only onceAC-014
Concurrent requests with the same keySend 50 concurrent requests with the same keyOnly one executes; the others return the same object or 409 operation_in_progressAC-015
Same key, different amountResubmit with the same key and a changed amount409 idempotency_conflictAC-016
New key, same order IDA new key + the same order IDNo second payment is createdAC-017
Retry with the same key and a different cardRetry with the same key but different card details (the test environment has only one generic test card, so re-enter it with a different expiry date)The original operation is reused, and the new card isn't chargedAC-018
Confirm with a new key while in progressWhile the C3 scenario is stopped at requires_action (in the test environment, on the simulated payment page), confirm with a new key409 payment_in_progressAC-027
Retry with the same key after a network timeoutSet the client timeout to 100 ms and make a C1 payment, then retry with the same keyYou get the same payment, charged only onceAC-069
Cancel a payment that may have been submittedCall cancel while the C3 scenario is at requires_action202, or the status stays unchanged; it becomes canceled only after the provider confirms the cancellation is safeAC-029
Environment isolationAfter the live environment is activated, retrieve a test payment by ID with a live key (or the reverse)404AC-002
Write with a read-only keyCreate a payment with a key that has only payments:read403 forbiddenAC-003
Recommended test order
Recommended test order

Merchant self-test checklist

Your checkmarks are saved only on this device. "How to test" jumps to the matching scenario row above.

0 of 33 completed

Payment 0/7Checkout 0/5Idempotency 0/8Refund 0/5Webhook 0/5Permissions and isolation 0/3

  • Payment

    MT-01A direct payment that needs no 3DS succeeds, and the order is fulfilled only oncePayment · Acceptance criteria AC-008 ·
  • MT-023DS challenge: full-page redirect to the authentication URL, and the return_url page relies on a server-side queryPayment · Acceptance criteria AC-009 ·
  • MT-033DS succeeds but the issuer declines: don't fulfill the order, and ask the payer to use another cardPayment · Acceptance criteria AC-012 ·
  • MT-04Another card after a decline: confirm with a new idempotency key, on the same PaymentPayment · Acceptance criteria AC-026 ·
  • MT-05Outcome unknown (202): show "Confirming", don't charge again, and handle the final result through an event or a queryPayment · Acceptance criteria AC-019 ·
  • MT-06USD and JPY amounts are converted correctly to the smallest currency unitPayment · Acceptance criteria AC-028 ·
  • MT-07Manually adding a parameter such as ?status=succeeded to the return_url doesn't trigger fulfillmentPayment · Acceptance criteria AC-013
  • Checkout

    MT-08A checkout payment that needs no 3DS succeeds, and the page, the query and the webhook show the same resultCheckout · Acceptance criteria AC-010 ·
  • MT-09A checkout payment with 3DS succeedsCheckout · Acceptance criteria AC-011 ·
  • MT-10Submitting from two tabs at the same time creates only one in-flight attemptCheckout · Acceptance criteria AC-024 ·
  • MT-11An expired session doesn't mark the order as failedCheckout · Acceptance criteria AC-025 ·
  • MT-12After the payer clicks "Return to merchant", query the status first and don't mark the order canceled directlyCheckout · Acceptance criteria Merchant-side counterpart ·
  • Idempotency

    MT-13Submitting 10 times with the same key creates only one PaymentIdempotency · Acceptance criteria AC-014 ·
  • MT-14Concurrent requests with the same key execute only onceIdempotency · Acceptance criteria AC-015 ·
  • MT-15The same key with a different amount returns 409 and triggers an alertIdempotency · Acceptance criteria AC-016 ·
  • MT-16A new key with the same order ID doesn't create a second PaymentIdempotency · Acceptance criteria AC-017 ·
  • MT-17Retrying with the same key and a different card doesn't charge the new cardIdempotency · Acceptance criteria AC-018 ·
  • MT-18Confirming with a new key while in progress is rejected and doesn't charge againIdempotency · Acceptance criteria AC-027 ·
  • MT-19After a 5xx or timeout, retry with the same key or check the status; your code has no "charge again with a new key" pathIdempotency · Acceptance criteria AC-069 ·
  • MT-20When you cancel a payment that may already have been submitted, rely on the canceled statusIdempotency · Acceptance criteria AC-029 ·
  • Refund

    MT-21A full refund passes an explicit amountRefund · Acceptance criteria AC-030 ·
  • MT-22The total of multiple partial refunds and refund_status are correctRefund · Acceptance criteria AC-031 ·
  • MT-23A refund that exceeds the refundable principal is rejected and the right message is shownRefund · Acceptance criteria AC-032 ·
  • MT-24Retrying with the same key after a refund timeout doesn't create a second refundRefund · Acceptance criteria AC-033 ·
  • MT-25When funds are insufficient, the shortfall is shown to the operator and the amount isn't reduced automaticallyRefund · Acceptance criteria AC-034 ·
  • Webhook

    MT-26After the request body is tampered with, signature verification fails and no business logic runsWebhook · Acceptance criteria AC-059 ·
  • MT-27An old event redelivered with a new signature time is accepted and deduplicated by event IDWebhook · Acceptance criteria AC-060 ·
  • MT-28Deliveries are retried on schedule after the endpoint fails, and missed events can be backfilled once it recoversWebhook · Acceptance criteria AC-061 ·
  • MT-29Internal-network or localhost addresses can't be configured as endpointsWebhook · Acceptance criteria AC-062 ·
  • MT-30Out-of-order events are processed by version, and an old event doesn't overwrite a newer stateWebhook · Acceptance criteria AC-022 (merchant-side counterpart) ·
  • Permissions and isolation

    MT-31Test keys and live keys can't access each other's objectsPermissions and isolation · Acceptance criteria AC-002 ·
  • MT-32A read-only key can't create refundsPermissions and isolation · Acceptance criteria AC-003 ·
  • MT-33Card numbers, CVCs, API keys, signing secrets and authentication links never appear in your logs or error reportingPermissions and isolation · Acceptance criteria AC-064 (merchant-side counterpart)

From test to live

ItemTestWhat to redo for live
API keyTest keyAn Owner or Admin creates it in the live environment (step-up verification required), with least-privilege scopes
WebhooksTest endpoint and secretConfigure the live endpoint and store the live signing secret
Redirect URLsTest URLsRegister URLs under your live domain
ProviderThe platform's built-in simulated provider; you choose the resultsThe live provider; the issuer and provider decide the results. 3DS challenges, frictionless 3DS, timeouts and duplicate callbacks can happen, so handle them as described under "Live behavior" in the test card table
CardsThe generic test cardReal cards; don't use test cards in live
RefundsSubmitted to the provider as soon as they're createdNothing to configure: in live, refunds are also submitted as soon as they're created
DisbursementsThe disbursement capability in the test environment and a test key with disbursement scopesThe platform enables the disbursement capability in the live environment and sets up the channel, limits and disbursement rates. Give the live key only the scopes disbursements need. Confirm each item in the disbursement go-live checklist
Next step—Confirm each item in the Go-live checklist
Was this page helpful?