Transaction Authorization

Sign payouts with the user's wallet when your company runs in Signature mode.

Before You Start

Read the following guides before proceeding:

GuideWhy
Api BasicsRequired headers and request configuration
AuthenticationThe user token that identifies the signer
EnvironmentsGET /api/v1/config returns your company's authorization mode

Overview

Every company runs in one of two transaction authorization modes, set by Wirex per company.

ModePayouts
External (default)Executed without a wallet signature. You authorize the user yourself before calling the API
SignatureEach payout carries transaction_authorization: a signature by the user's wallet over a fixed sentence that names the operation, the estimation and a nonce

A refused signature moves no funds and spends no estimation.

Reading the Mode

GET /api/v1/config

Without a user token, send your company id (UUID) in X-Company-Id.

{
  "defaultCompanyId": "00000000-0000-0000-0000-000000000044",
  "transactionAuthorizationMode": "External"
}

Read the mode once at startup and branch on it.


Endpoints

MethodPathOperationSignature
POST/api/v1/bank/transferBankTransferRequired in Signature mode — see SEPA Bank Transfer and ACH Bank Transfer
POST/api/v3/bank/initiate/{corridor}CorridorTransferInitiateRequired in Signature mode, on every corridor — see Corridor Transfers
POST/api/v1/cards/transferCardTransferRequired in Signature mode — see Card Transfer
POST/api/v2/recipientsRecipientCreateOptional. Verified only for agent companies in Signature mode; otherwise only its shape is checked — see Create Recipients

The signer is the user's wallet — the address Wirex resolves for the authenticated user (on EVM, the EOA, not the Smart Wallet).


The transaction_authorization Object

{
  "transaction_authorization": {
    "message_signature": "0x1c8aff950685c2ed4bc3174f3472287b56d9517b9c948127319a09a7a36deac81f0c5b0e4a7c1d2e3f405162738495a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c1b",
    "nonce": 1704103200
  }
}
FieldTypeRequiredDescription
transaction_authorizationobjectConditionalRequired on the payout endpoints in Signature mode
transaction_authorization.message_signaturestringYesSignature over the sentence. Encoding per chain in Signing
transaction_authorization.nonceinteger (int64)YesThe Unix time, in seconds, at which the sentence was formed. Not 0, not more than 5 minutes old, not more than 60 seconds in the future
transaction_authorization.public_keystringConditionalXRPL wallets only: the signer's public key in hex

Each signature is accepted once, even when the execution behind it fails. A retry needs a new nonce and a
new signature.


The Sentence

Every character of the sentence is signed. Build it from the request you are about to send.

Payouts

I confirm that I'm executing <operation> according to estimation <estimation_id> at <nonce>
PlaceholderValue
<operation>BankTransfer, CorridorTransferInitiate or CardTransfer, from the Endpoints table
<estimation_id>The request's estimation_id as a lowercase, hyphenated UUID
<nonce>The same integer as transaction_authorization.nonce

Example, for POST /api/v3/bank/initiate/sepa with estimation_id 00000000-0000-0000-0000-000000000001
and nonce 1704103200:

I confirm that I'm executing CorridorTransferInitiate according to estimation 00000000-0000-0000-0000-000000000001 at 1704103200

Recipient Creation

I confirm I save recipient <name> <details> at <nonce>

<name> is company_name for a business, first_name + space + last_name for an individual, and
nick_name for a CrossChainCrypto recipient or a Crypto recipient without names.

<details>, by payment detail type:

type<details>
SepaIBAN <iban> BIC <bic> — both upper-cased, with every space removed
Achaccount number <account_number> routing number <routing_number>
Fedwireaccount number <account_number> routing number <routing_number> — the same sentence as Ach
Cryptoaddress <address> on <network> — an EVM address in its EIP-55 checksum form
CrossChainCryptoaddress <address> on <network> — a 0x address is written in EIP-55 form when network is EVM, and as sent otherwise. tag must be empty
Cardcard ending <card_pan_last> with id <card_id>

Other types are not covered on this page; create them without transaction_authorization.

Example, for an individual SEPA recipient:

I confirm I save recipient Alex Grey IBAN DE89370400440532013000 BIC COBADEFF at 1704103200

Signing

WalletSignature
EVM EOAEIP-191 personal_sign over the sentence, hex-encoded with 0x. v may be 27/28 or 0/1
EVM smart-contract walletERC-1271 isValidSignature over the EIP-191 hash
Stellared25519 over the SHA-256 digest of the sentence, base64-encoded
XRPLed25519 or secp256k1 over the sentence, hex-encoded. Send the signer's public_key; the address derived from it must be the user's address
// EVM, with viem
const nonce = Math.floor(Date.now() / 1000);
const message = `I confirm that I'm executing CorridorTransferInitiate according to estimation ${estimationId} at ${nonce}`;
const messageSignature = await walletClient.signMessage({ account: userEoaAddress, message });

const response = await fetch(`${baseUrl}/api/v3/bank/initiate/sepa`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'X-User-Wallet': userEoaAddress,
    'X-Chain-Id': chainId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    estimation_id: estimationId,
    source_token_address: tokenAddress,
    transaction_authorization: { message_signature: messageSignature, nonce }
  })
});
# EVM, with eth-account
import time
from eth_account import Account
from eth_account.messages import encode_defunct

nonce = int(time.time())
message = f"I confirm that I'm executing CorridorTransferInitiate according to estimation {estimation_id} at {nonce}"
signed = Account.sign_message(encode_defunct(text=message), private_key=user_private_key)

response = requests.post(
    f"{base_url}/api/v3/bank/initiate/sepa",
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-User-Wallet": user_eoa_address,
        "X-Chain-Id": chain_id,
        "Content-Type": "application/json"
    },
    json={
        "estimation_id": estimation_id,
        "source_token_address": token_address,
        "transaction_authorization": {
            "message_signature": "0x" + signed.signature.hex().removeprefix("0x"),
            "nonce": nonce
        }
    }
)
// EVM, with go-ethereum
nonce := time.Now().Unix()
message := fmt.Sprintf("I confirm that I'm executing CorridorTransferInitiate according to estimation %s at %d", estimationId, nonce)
signature, _ := crypto.Sign(accounts.TextHash([]byte(message)), userPrivateKey)
signature[64] += 27

body, _ := json.Marshal(map[string]interface{}{
    "estimation_id":        estimationId,
    "source_token_address": tokenAddress,
    "transaction_authorization": map[string]interface{}{
        "message_signature": hexutil.Encode(signature),
        "nonce":             nonce,
    },
})

req, _ := http.NewRequest("POST", baseURL+"/api/v3/bank/initiate/sepa", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("X-User-Wallet", userEoaAddress)
req.Header.Set("X-Chain-Id", chainId)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Sign as close to the call as possible: the nonce is valid for 5 minutes.


Error Handling

{
  "error_reason": "ErrorPermissionDenied",
  "error_description": "transaction authorization does not authorize this request",
  "error_category": {
    "category": "CategoryUnauthorized",
    "http_status_code": 401
  }
}

Signature errors are 401, malformed transaction_authorization is 400.

Error ReasonStatusDescriptionResolution
ErrorMissingField401transaction authorization is requiredSignature mode: sign and send it
ErrorExpired401transaction authorization has expirednonce older than 5 minutes. Sign again
ErrorNotYetValid401transaction authorization is not yet valid, check the device clocknonce more than 60 seconds in the future. Check the signing device's clock
ErrorPermissionDenied401transaction authorization does not authorize this requestThe sentence or signer does not match the request. Rebuild the sentence and sign again
ErrorAlreadyExists401transaction authorization has already been usedSign again with a new nonce
ErrorMissingField / ErrorInvalidField400Missing message_signature or nonce, undecodable signature, or (agent companies) an unsignable recipient typeFix the field named in error_details
ErrorGeneral503Transaction authorization is temporarily unavailableNothing was executed. Retry with a new signature

Did this page help you?