Transaction API

This endpoint is used to inspect the current state of a payout or quote conversion. It returns the original quote details, recipient information, state transitions, and timestamps to support reconciliation.

Endpoint

GET {{baseURL}}/v1/transaction/{transactionId}

Request headers

Header	Description	Required	Example
`x-api-key`	Workspace API key for authentication.	✅ Yes	`YOUR_API_KEY`
`Content-Type`	Media type of the request.	✅ Yes	`application/json`

Request examples

curl --request GET '{{baseURL}}/v1/transaction/8c684c17-ef91-4133-a624-xxxxxxxxxxxxx' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'

const transactionId = '8c684c17-ef91-4133-a624-xxxxxxxxxxxxx';

fetch(`{{baseURL}}/v1/transaction/${transactionId}`, {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
})
  .then((res) => {
    if (!res.ok) {
      throw new Error(`Request failed with status ${res.status}`);
    }
    return res.json();
  })
  .then((body) => console.log(body))
  .catch((error) => console.error('Failed to fetch transaction', error));

import requests

transaction_id = "8c684c17-ef91-4133-a624-xxxxxxxxxxxxx"
url = f"{{baseURL}}/v1/transaction/{transaction_id}"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.get(url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const axios = require('axios');

const transactionId = '8c684c17-ef91-4133-a624-xxxxxxxxxxxxx';

axios.get(`{{baseURL}}/v1/transaction/${transactionId}`, {
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  timeout: 30000
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    if (error.response) {
      console.error('API error:', error.response.data);
    } else {
      console.error('Request error:', error.message);
    }
  });

Successful response

copy

{
  "message": "transaction fetched successfully",
  "status": "success",
  "data": {
    "id": "8c684c17-ef91-4133-a624-xxxxxxxxxxxxx",
    "remark": "Tested",
    "reason": "Gift",
    "referenceNumber": "W1TDB6RWSQMKF",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "b39b64b9-3ca0-4566-b66b-xxxxxxxxxxxxx",
      "source": {
        "currency": "NGN",
        "country": "NG",
        "amount": 15000
      },
      "target": {
        "currency": "USD",
        "country": "US",
        "amount": 100
      },
      "rate": 1500,
      "fee": {
        "amount": 100
      }
    },
    "recipient": {
      "name": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "relationship": "SELF",
      "type": "BANK",
      "account": {
        "sortCode": "058",
        "accountNumber": "86123435XXXXX"
      },
      "paymentChannel": "SWIFT_OURS",
      "currency": "USD",
      "country": "US"
    },
    "created": "2024-02-27T14:17:48.038Z",
    "processed": "2024-02-27T14:20:49.712Z"
  }
}

Field reference

Field	Type	Description
`data.id`	String	Unique transaction identifier.
`data.state`	String	Current processing state (e.g. `PENDING`, `COMPLETED`, `FAILED`).
`data.referenceNumber`	String	meCash-generated reference for reconciliation.
`data.quote`	Object	Quote snapshot used to execute the payout.
`data.recipient`	Object	Beneficiary information used during disbursement.
`data.created`	String	Timestamp (ISO 8601) when the transaction was created.
`data.processed`	String	Timestamp for the latest state change.

Error responses

Status	Meaning	Example message	Next steps
400	Transaction not found or invalid ID.	`Transaction does not exist`	Confirm the identifier and ensure the payout was created successfully.
401	Authentication failed.	`Invalid API key`	Verify the `x-api-key` header.
403	IP not whitelisted.	`Access denied: IP address not whitelisted`	Add your server IP under Developers → IP Whitelisting.
422	Invalid parameter.	`Invalid parameter`	Check that the `transactionId` is a valid UUID.
429	Too many requests.	`Too many requests`	Add exponential backoff before retrying.
500	Server error.	`Internal server error`	Retry later or contact support if persistent.

Usage tips

Call this endpoint after receiving payout webhooks to verify the final state and amounts.
Persist transaction responses for audit trails; they include the original quote snapshot.
If the transaction remains PROCESSING for longer than expected, reach out to support with the referenceNumber for investigation.
Transactions are created when you call POST /v2/payout or the Bulk Payout API.

Overview

Wallets

Quotes

Payouts

Virtual Accounts

Ramp

Transactions

Webhooks

Endpoint

Request headers

Request examples

Successful response

Field reference

Error responses

Usage tips

​Endpoint

​Request headers

​Request examples

​Successful response

​Field reference

​Error responses

​Usage tips

Endpoint

Request headers

Request examples

Successful response

Field reference

Error responses

Usage tips