Helper API Reference
API reference for sandbox test event simulation.
Before You Start
Read the following guides before proceeding:
| Guide | Why |
|---|---|
| Getting Started | Platform overview and setup |
| Api Basics | Required headers and request configuration |
| Authentication | How to obtain access tokens |
| Onboarding | User and wallet registration |
| KYC | KYC verification requirements |
Overview
The Sandbox Helper API at https://ramc.wirexapp.tech provides endpoints to simulate external events for testing. All endpoints use the user's email address to identify accounts.
Interactive API documentation is available at https://ramc.wirexapp.tech/api-docs/.
Mint Test Tokens
Mint test tokens directly to a user's wallet for testing purposes.
Endpoint
POST /account/retail/mint
Request
{
"chainId": "84532",
"token": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976",
"to": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
"amount": "1000000000000000000"
}| Field | Type | Required | Description |
|---|---|---|---|
chainId | string | Yes | Chain ID (84532 for Base Sepolia) |
token | string | Yes | Token contract address |
to | string | Yes | Destination wallet address |
amount | string | Yes | Amount in the token's smallest unit (wei) — multiply by 10^decimals |
The amount is in the smallest unit, not whole tokens. WUSD/WEUR have 18 decimals, so 1 WUSD/WEUR is "1000000000000000000".
See Credentials for sandbox token addresses.
Response
{
"txHash": "0x28da8dec81198cd43329c92ac5b7bcb048a48495bdbc69fc1c921da72fe42939",
"success": true
}SEPA Operations
Simulate SEPA Deposit
Simulate an incoming SEPA EUR deposit to a user's account.
Endpoint
POST /bank/sepa/deposit
Request
{
"region": "GB",
"email": "[email protected]",
"amount": 250.00
}| Field | Type | Required | Description |
|---|---|---|---|
region | string | No | Region code (GB or EEA). Always use GB for now. |
email | string | Yes | User's email address |
amount | number | Yes | Amount in EUR |
Response
{
"success": true
}This triggers a /v2/webhooks/activities webhook with type Sepa and direction Inbound.
Get Pending SEPA Transfers
List pending outbound SEPA transfers waiting for completion.
Note: In sandbox environment, all outbound SEPA transfers remain in pending state indefinitely. Use
completeorrevertendpoints to simulate the external banking system processing the transfer.
Endpoint
GET /bank/sepa/transfers/pending
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
region | string | No | Region code (GB or EEA). Always use GB for now. |
email | string | Yes | User's email address |
Response
[
{
"id": "txn_abc123def456",
"transactionId": "OP-12345",
"status": "RELEASED",
"type": "PAYOUT",
"amount": {
"currency": "EUR",
"value": 150.00
}
}
]Use the id value in transfer completion/revert requests.
Complete SEPA Transfer
Mark a pending outbound SEPA transfer as completed.
Endpoint
POST /bank/sepa/transfer/complete
Request
{
"region": "GB",
"email": "[email protected]",
"transactionId": "txn_abc123def456"
}| Field | Type | Required | Description |
|---|---|---|---|
region | string | No | Region code (GB or EEA). Always use GB for now. |
email | string | Yes | User's email address |
transactionId | string | Yes | Transaction ID from pending list |
Response
{
"success": true
}This triggers a /v2/webhooks/activities webhook with status Completed.
Revert SEPA Transfer
Simulate a returned SEPA transfer. This can only be called after a transfer has been completed. Creates an inbound reversal transaction that credits the funds back to the user's account.
Endpoint
POST /bank/sepa/transfer/revert
Request
{
"region": "GB",
"email": "[email protected]",
"transactionId": "txn_abc123def456"
}Response
{
"success": true
}This triggers a /v2/webhooks/activities webhook with type Sepa, direction Inbound, representing the reversal credit.
ACH Operations
Activate ACH Customer
Activate a user's ACH account. Required before ACH deposits can be simulated.
Note: In sandbox environment, ACH accounts remain in pending state indefinitely after creation. Call this endpoint to simulate the external ACH provider activating the account.
Endpoint
POST /bank/ach/customer/activate
Request
{
"email": "[email protected]"
}| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | User's email address |
Response
{
"success": true
}Simulate ACH Deposit
Simulate an incoming ACH USD deposit to a user's account.
Endpoint
POST /bank/ach/deposit
Request
{
"email": "[email protected]",
"amount": 500.00
}| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | User's email address |
amount | number | Yes | Amount in USD |
Response
{
"success": true
}This triggers a /v2/webhooks/activities webhook with type AchPush and direction Inbound.
Complete ACH Transfer
Mark a pending outbound ACH transfer as completed.
Note: In sandbox environment, all outbound ACH transfers remain in pending state indefinitely. Use
completeorrevertendpoints to simulate the external ACH network processing the transfer.
Endpoint
POST /bank/ach/transfer/complete
Request
{
"externalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}| Field | Type | Required | Description |
|---|---|---|---|
externalId | string | Yes | Activity ID from Wirex BaaS transfer response |
Response
{
"success": true
}Revert ACH Transfer
Simulate a returned ACH transfer. This can only be called after a transfer has been completed. Creates an inbound reversal transaction that credits the funds back to the user's account.
Endpoint
POST /bank/ach/transfer/revert
Request
{
"externalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}Response
{
"success": true
}Card Transaction Operations
Simulate card transactions for testing card payment flows. Each endpoint runs a complete ISO-8583 message flow (authorization, clearing, reversal, refund, etc.) against a card and triggers the corresponding activity webhooks.
Common Parameters
All card flow endpoints accept the same base request format:
{
"cardId": "550e8400-e29b-41d4-a716-446655440000",
"amount": 25.50,
"currency": "GBP",
"settlementAmount": 25.50,
"settlementCurrency": "GBP",
"merchantCountry": "GBR",
"paymentProvider": "Visa"
}| Field | Type | Required | Description |
|---|---|---|---|
cardId | string (UUID) | Yes | Card ID from Wirex BaaS |
amount | number | Yes | Transaction amount |
currency | string | Yes | Transaction currency (ISO 4217, e.g. GBP) |
settlementAmount | number | Yes | Settlement (billing) amount |
settlementCurrency | string | Yes | Settlement currency (ISO 4217) |
merchantCountry | string | No | Merchant country (ISO 3166 alpha-3, e.g. GBR) |
paymentProvider | string | No | Visa, MasterCard, or VisaEFunds |
For a same-currency purchase, set settlementAmount/settlementCurrency equal to amount/currency. To simulate FX, use different values.
POST /card/auth-and-multi-clearing additionally requires clearingAmounts (array of numbers) — the per-clearing local amounts whose sum equals the auth amount.
Common Response
Each flow returns the ISO messages it produced. Fields are present only when the flow generates them.
{
"transactionIdentifier": "a1b2c3d4-0000-0000-0000-000000000000",
"auth": { },
"clearing": { },
"refund": { },
"reversal": { },
"representment": { },
"adjustment": { },
"auths": [ ],
"clearings": [ ]
}| Field | Type | Description |
|---|---|---|
transactionIdentifier | string | Identifier linking the messages in this flow |
auth | object | Authorization message (when produced) |
clearing | object | Clearing/settlement message (when produced) |
refund | object | Refund message (when produced) |
reversal | object | Reversal message (when produced) |
representment | object | Representment message (when produced) |
adjustment | object | Adjustment message (when produced) |
auths | array | Multiple authorizations (multi-auth flows) |
clearings | array | Multiple clearings (multi-clearing flows) |
Common Flows
| Purpose | Endpoint |
|---|---|
| In-store purchase (auth + clearing) | POST /card/auth-and-clearing |
| E-commerce / card-not-present purchase | POST /card/epos-auth-and-clearing |
| ATM cash withdrawal | POST /card/atm-auth-and-clearing |
| Standalone refund | POST /card/standalone-refund |
| Push funds to card (Original Credit) | POST /card/original-credit |
| Balance inquiry | POST /card/balance-inquiry |
Example — Purchase (auth + clearing)
POST /card/auth-and-clearing
Request:
{
"cardId": "550e8400-e29b-41d4-a716-446655440000",
"amount": 25.50,
"currency": "GBP",
"settlementAmount": 25.50,
"settlementCurrency": "GBP",
"merchantCountry": "GBR",
"paymentProvider": "Visa"
}Response:
{
"transactionIdentifier": "a1b2c3d4-0000-0000-0000-000000000000",
"auth": { },
"clearing": { }
}This triggers /v2/webhooks/activities webhooks with type CardTransaction.
All Flow Endpoints
| Endpoint | Description |
|---|---|
POST /card/auth-and-clearing | Authorization + clearing (standard purchase) |
POST /card/epos-auth-and-clearing | E-commerce (card-not-present) auth + clearing |
POST /card/atm-auth-and-clearing | ATM auth + clearing |
POST /card/fuel-dispenser-auth-and-clearing | Fuel dispenser (full reversal + delayed auth) + clearing |
POST /card/multi-auth-and-clearing | Multiple authorizations + clearing |
POST /card/auth-and-multi-clearing | One auth + multiple partial clearings (clearingAmounts) |
POST /card/auth-partial-reversal | Auth + partial reversal |
POST /card/auth-full-reversal | Auth + full reversal |
POST /card/auth-reversal-clearing | Auth + reversal + clearing |
POST /card/standalone-reversal | Standalone reversal |
POST /card/standalone-clearing | Standalone clearing |
POST /card/standalone-refund | Standalone refund |
POST /card/original-credit | Original Credit Transaction (push funds to card) |
POST /card/auth-clearing-full-refund | Auth + clearing + full refund |
POST /card/auth-clearing-partial-refund | Auth + clearing + partial refund |
POST /card/check-refund | Check refund |
POST /card/auth-clearing-refund-representment | Auth + clearing + refund + representment |
POST /card/auth-clearing-partial-refund-representment | Auth + clearing + partial refund + representment |
POST /card/auth-clearing-full-reversal-representment | Auth + clearing + full reversal + representment |
POST /card/auth-clearing-partial-reversal-representment | Auth + clearing + partial reversal + representment |
POST /card/auth-chargeback-clearing | Auth + chargeback advice + clearing |
POST /card/auth-clearing-with-correction | Auth + clearing with correction |
POST /card/credit-adjustment | Credit adjustment |
POST /card/debit-adjustment | Debit adjustment |
POST /card/balance-inquiry | Balance inquiry |
Code Examples
JavaScript
const HELPER_API = 'https://ramc.wirexapp.tech';
// Simulate SEPA deposit
async function simulateSepaDeposit(email, amount) {
const response = await fetch(`${HELPER_API}/bank/sepa/deposit`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
region: 'GB',
email,
amount
})
});
return response.json();
}
// Complete SEPA transfer
async function completeSepaTransfer(email, transactionId) {
const response = await fetch(`${HELPER_API}/bank/sepa/transfer/complete`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
region: 'GB',
email,
transactionId
})
});
return response.json();
}
// Simulate card purchase (auth + clearing)
async function simulateCardPurchase(cardId, amount, currency = 'GBP') {
const response = await fetch(`${HELPER_API}/card/auth-and-clearing`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
cardId,
amount,
currency,
settlementAmount: amount,
settlementCurrency: currency,
paymentProvider: 'Visa'
})
});
return response.json();
}Python
import requests
HELPER_API = 'https://ramc.wirexapp.tech'
def simulate_sepa_deposit(email: str, amount: float) -> dict:
response = requests.post(
f'{HELPER_API}/bank/sepa/deposit',
json={
'region': 'GB',
'email': email,
'amount': amount
}
)
return response.json()
def complete_sepa_transfer(email: str, transaction_id: str) -> dict:
response = requests.post(
f'{HELPER_API}/bank/sepa/transfer/complete',
json={
'region': 'GB',
'email': email,
'transactionId': transaction_id
}
)
return response.json()
def simulate_card_purchase(card_id: str, amount: float, currency: str = 'GBP') -> dict:
response = requests.post(
f'{HELPER_API}/card/auth-and-clearing',
json={
'cardId': card_id,
'amount': amount,
'currency': currency,
'settlementAmount': amount,
'settlementCurrency': currency,
'paymentProvider': 'Visa'
}
)
return response.json()Go
package main
import (
"bytes"
"encoding/json"
"net/http"
)
const helperAPI = "https://ramc.wirexapp.tech"
type SepaDepositRequest struct {
Region string `json:"region"`
Email string `json:"email"`
Amount float64 `json:"amount"`
}
type CardTransactionRequest struct {
CardID string `json:"cardId"`
Amount float64 `json:"amount"`
Currency string `json:"currency"`
SettlementAmount float64 `json:"settlementAmount"`
SettlementCurrency string `json:"settlementCurrency"`
PaymentProvider string `json:"paymentProvider"`
}
func simulateSepaDeposit(email string, amount float64) error {
body, _ := json.Marshal(SepaDepositRequest{
Region: "GB",
Email: email,
Amount: amount,
})
_, err := http.Post(
helperAPI+"/bank/sepa/deposit",
"application/json",
bytes.NewBuffer(body),
)
return err
}
func simulateCardPurchase(cardID string, amount float64, currency string) error {
body, _ := json.Marshal(CardTransactionRequest{
CardID: cardID,
Amount: amount,
Currency: currency,
SettlementAmount: amount,
SettlementCurrency: currency,
PaymentProvider: "Visa",
})
_, err := http.Post(
helperAPI+"/card/auth-and-clearing",
"application/json",
bytes.NewBuffer(body),
)
return err
}Error Handling
All endpoints return errors in this format:
{
"error": "User not found for email: [email protected]"
}| HTTP Status | Description |
|---|---|
| 400 | Missing required parameters |
| 500 | Operation failed (user not found, API error, etc.) |

