Sandbox Testing for Payouts

Before you send payouts to real beneficiaries in Production, use the Stage environment to confirm your integration handles both successful payouts and the rejection scenarios beneficiaries' banks return in practice. This guide covers the Bank Transfer payout sandbox flow and provides dedicated test accounts, one per country, that deterministically trigger each rejection scenario.

Before You Begin

• Valid API credentials (access token) for Stage.
• Familiarity with Send funds via Bank Transfer and the Create a Payout request structure.
• A webhook endpoint configured to receive payout status notifications.

---

How the Sandbox Simulates Rejections

Stage does not move real money, but it follows the same flow as Production: Localpayment receives your request, validates the request structure, and if it's correctly formatted, sets it to In Progress and routes it for a simulated bank response based on the account details you submit. That response decides whether to approve or reject the payout. You find out the result the normal way: by webhook, or by querying the transaction status.

Any payout with a correctly structured request is approved automatically. The test accounts in this guide are the exception: each one is mapped to a specific rejection reason, so you can reproduce that error condition on demand instead of waiting for it to occur naturally.

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'actorBkg': '#31467c', 'actorBorder': '#0c1a29', 'actorTextColor': '#ffffff', 'actorLineColor': '#0c1a29', 'signalColor': '#0c1a29', 'signalTextColor': '#0c1a29', 'labelBoxBkgColor': '#31467c', 'labelBoxBorderColor': '#0c1a29', 'labelTextColor': '#ffffff', 'loopTextColor': '#0c1a29', 'noteBkgColor': '#ffffff', 'noteBorderColor': '#31467c', 'noteTextColor': '#0c1a29'}}}%%
sequenceDiagram
  autonumber
  participant Dev as Your Backend
  participant LP as Localpayment (Stage)
  participant Bank as Simulated Bank Response

  Dev->>LP: POST /api/payout/ (test beneficiary.bank details)
  LP->>LP: Validate request fields
  LP-->>Dev: Response: status In Progress
  LP->>Bank: Route the payout
  Bank-->>LP: Approve, or reject with the mapped test code
  alt Rejected
    LP-->>Dev: Webhook: status REJECTED (code / description)
  else Approved
    LP-->>Dev: Webhook: status COMPLETED
  end
  Dev->>LP: (or) GET payout status
  LP-->>Dev: Current status

1. You submit a payout in Stage using one of the test accounts from the tables below.
2. Localpayment validates the request structure and, if it's valid, sets the payout to In Progress while it routes for a simulated bank response.
3. The simulated bank response evaluates the beneficiary account details. A correctly structured account that doesn't match one of the test accounts below is approved automatically. A test account is rejected with its mapped code.
4. Localpayment notifies you of the final status through your webhook endpoint, or you retrieve it by querying the transaction. Use this to confirm your integration reacts correctly to REJECTED payouts without waiting for a real bank rejection.

---

Rejection Codes

Each test account below returns one of these five outcomes. All resolve to a REJECTED payout with the corresponding status.code and status.description.

---

Test Accounts by Country

Each tab lists the beneficiary bank details for one country. Every scenario shares the same paymentMethod.code and, unless noted otherwise, the same beneficiary.bank.code and beneficiary.bank.name for that country. account.details is the value to send in beneficiary.bank.account.number (or beneficiary.bank.account.alias, where noted) to trigger the matching rejection code. Description is the status.description you'll see in the response and webhook for that code.

---

Field Mapping Reference

The test accounts above populate the standard beneficiary.bank object from Create a Payout:

Account numbers that pass check-digit validation (Mexico CLABE, Argentina CBU, and the IBAN formats used by Costa Rica, Dominican Republic, and El Salvador) are structurally valid test values, not real accounts. They exist only to reach the mapped rejection scenario.

---

Next Steps