Transactions API

Create and manage money transfer transactions.

Create Transaction

Withdraw (default)

Send funds to a customer’s destination payment method:


const transaction = await afriex.transactions.create({
  customerId: "customer-id",
  sourceAmount: "10",
  destinationAmount: "5000",
  sourceCurrency: "USD",
  destinationCurrency: "NGN",
  destinationId: "payment-method-id",
  meta: {
    reference: "ref-withdraw-001",
    idempotencyKey: "unique-key-123",
    narration: "Payment for services",
  },
});

Deposit

Pull funds from a customer’s source payment method:


const transaction = await afriex.transactions.create({
  customerId: "customer-id",
  type: "DEPOSIT",
  sourceAmount: "10",
  destinationAmount: "5000",
  sourceCurrency: "USD",
  destinationCurrency: "NGN",
  sourceId: "source-payment-method-id",
  meta: {
    reference: "ref-deposit-001",
    idempotencyKey: "unique-key-456",
  },
});

Request Parameters:

Field	Type	Required	Description
`customerId`	`string`	Yes	ID of the customer
`sourceAmount`	`${number}`	Yes	Amount in source currency
`destinationAmount`	`${number}`	Yes	Amount in destination currency
`sourceCurrency`	`string`	Yes	Source currency code (e.g., `USD`)
`destinationCurrency`	`string`	Yes	Target currency code (e.g., `NGN`)
`type`	`string`	-	`WITHDRAW` (default), `DEPOSIT`, or `SWAP`
`destinationId`	`string`	Yes for `WITHDRAW`	Payment method ID to send funds to
`sourceId`	`string`	Yes for `DEPOSIT`	Payment method ID to pull funds from
`meta.reference`	`string`	Yes	Your internal reference (e.g., order ID)
`meta.idempotencyKey`	`string`	Yes	Unique key to prevent duplicate transactions
`meta.narration`	`string`	-	Transaction description
`meta.invoice`	`string`	-	Base64-encoded invoice document
`meta.merchantId`	`string`	-	Your merchant/business identifier

Get Transaction


const transaction = await afriex.transactions.get("transaction-id");

List Transactions


const response = await afriex.transactions.list({
  page: 1,
  limit: 20,
});
 
console.log(response.data); // Transaction[]

Transaction Status

Transactions can have the following statuses:

Status	Description
`PENDING`	Transaction created, awaiting processing
`PROCESSING`	Transaction is being processed
`COMPLETED`	Transaction completed successfully
`SUCCESS`	Transaction successful
`FAILED`	Transaction failed
`CANCELLED`	Transaction was cancelled
`REFUNDED`	Transaction was refunded
`RETRY`	Transaction is being retried
`REJECTED`	Transaction was rejected
`IN_REVIEW`	Transaction is under review
`UNKNOWN`	Transaction status is unknown