Helper API Reference

API reference for sandbox test event simulation.

Before You Start

Read the following guides before proceeding:

GuideWhy
Getting StartedPlatform overview and setup
Api BasicsRequired headers and request configuration
AuthenticationHow to obtain access tokens
OnboardingUser and wallet registration
KYCKYC 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"
}
FieldTypeRequiredDescription
chainIdstringYesChain ID (84532 for Base Sepolia)
tokenstringYesToken contract address
tostringYesDestination wallet address
amountstringYesAmount 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
}
FieldTypeRequiredDescription
regionstringNoRegion code (GB or EEA). Always use GB for now.
emailstringYesUser's email address
amountnumberYesAmount 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 complete or revert endpoints to simulate the external banking system processing the transfer.

Endpoint

GET /bank/sepa/transfers/pending

Query Parameters

ParameterTypeRequiredDescription
regionstringNoRegion code (GB or EEA). Always use GB for now.
emailstringYesUser'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"
}
FieldTypeRequiredDescription
regionstringNoRegion code (GB or EEA). Always use GB for now.
emailstringYesUser's email address
transactionIdstringYesTransaction 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]"
}
FieldTypeRequiredDescription
emailstringYesUser'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
}
FieldTypeRequiredDescription
emailstringYesUser's email address
amountnumberYesAmount 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 complete or revert endpoints to simulate the external ACH network processing the transfer.

Endpoint

POST /bank/ach/transfer/complete

Request

{
  "externalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
FieldTypeRequiredDescription
externalIdstringYesActivity 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"
}
FieldTypeRequiredDescription
cardIdstring (UUID)YesCard ID from Wirex BaaS
amountnumberYesTransaction amount
currencystringYesTransaction currency (ISO 4217, e.g. GBP)
settlementAmountnumberYesSettlement (billing) amount
settlementCurrencystringYesSettlement currency (ISO 4217)
merchantCountrystringNoMerchant country (ISO 3166 alpha-3, e.g. GBR)
paymentProviderstringNoVisa, 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": [ ]
}
FieldTypeDescription
transactionIdentifierstringIdentifier linking the messages in this flow
authobjectAuthorization message (when produced)
clearingobjectClearing/settlement message (when produced)
refundobjectRefund message (when produced)
reversalobjectReversal message (when produced)
representmentobjectRepresentment message (when produced)
adjustmentobjectAdjustment message (when produced)
authsarrayMultiple authorizations (multi-auth flows)
clearingsarrayMultiple clearings (multi-clearing flows)

Common Flows

PurposeEndpoint
In-store purchase (auth + clearing)POST /card/auth-and-clearing
E-commerce / card-not-present purchasePOST /card/epos-auth-and-clearing
ATM cash withdrawalPOST /card/atm-auth-and-clearing
Standalone refundPOST /card/standalone-refund
Push funds to card (Original Credit)POST /card/original-credit
Balance inquiryPOST /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

EndpointDescription
POST /card/auth-and-clearingAuthorization + clearing (standard purchase)
POST /card/epos-auth-and-clearingE-commerce (card-not-present) auth + clearing
POST /card/atm-auth-and-clearingATM auth + clearing
POST /card/fuel-dispenser-auth-and-clearingFuel dispenser (full reversal + delayed auth) + clearing
POST /card/multi-auth-and-clearingMultiple authorizations + clearing
POST /card/auth-and-multi-clearingOne auth + multiple partial clearings (clearingAmounts)
POST /card/auth-partial-reversalAuth + partial reversal
POST /card/auth-full-reversalAuth + full reversal
POST /card/auth-reversal-clearingAuth + reversal + clearing
POST /card/standalone-reversalStandalone reversal
POST /card/standalone-clearingStandalone clearing
POST /card/standalone-refundStandalone refund
POST /card/original-creditOriginal Credit Transaction (push funds to card)
POST /card/auth-clearing-full-refundAuth + clearing + full refund
POST /card/auth-clearing-partial-refundAuth + clearing + partial refund
POST /card/check-refundCheck refund
POST /card/auth-clearing-refund-representmentAuth + clearing + refund + representment
POST /card/auth-clearing-partial-refund-representmentAuth + clearing + partial refund + representment
POST /card/auth-clearing-full-reversal-representmentAuth + clearing + full reversal + representment
POST /card/auth-clearing-partial-reversal-representmentAuth + clearing + partial reversal + representment
POST /card/auth-chargeback-clearingAuth + chargeback advice + clearing
POST /card/auth-clearing-with-correctionAuth + clearing with correction
POST /card/credit-adjustmentCredit adjustment
POST /card/debit-adjustmentDebit adjustment
POST /card/balance-inquiryBalance 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 StatusDescription
400Missing required parameters
500Operation failed (user not found, API error, etc.)