Create Payment

Create a new payment of any type.

POST /v1/payments

Required Permission: payment:create

Request Body:

Field	Type	Required	Description
type	string	Yes	transfer, gift, request, merchant, or bank_confirmation
fiatAmount	number	Conditional	Amount in fiat currency (required unless cryptoAmount provided)
cryptoAmount	number	Conditional	Crypto amount for crypto-first mode (not valid for request)
fiatCurrency	string	Yes	NGN, GHS, KES, ZAR
crypto	string	Conditional	Required for transfer/gift/merchant/bank_confirmation; optional for request
network	string	Conditional	Required for transfer/gift/merchant/bank_confirmation; optional for request
chargeFrom	string	Required for transfer	"fiat" — fee from payout; "crypto" — fee added to crypto
payer	object	Conditional	Required for transfer/gift; not allowed for request
payer.chatId	string	Yes (if payer)	Payer identifier
payer.phone	string	No	Payer phone number
receiver	object	Conditional	Required for transfer/request; not allowed for gift/bank_confirmation
receiver.bankCode	string	Yes (if receiver)	Bank code
receiver.accountNumber	string	Yes (if receiver)	Account number
bankRef	string	No	Bank's internal reference (bank_confirmation type only)
metadata	object	No	Custom data for your reference
callbackUrl	string	No	URL for status callbacks

Example: Create Transfer

POST /v1/payments
{
  "type": "transfer",
  "fiatAmount": 10000,
  "fiatCurrency": "NGN",
  "crypto": "USDT",
  "network": "trc20",
  "chargeFrom": "fiat",
  "payer": {
    "chatId": "7389201648"
  },
  "receiver": {
    "bankCode": "090405",
    "accountNumber": "8012345678"
  },
  "metadata": {
    "orderId": "ORD-001",
    "description": "Product purchase"
  }
}

Response:

{
  "success": true,
  "payment": {
    "reference": "2S-7N4VFR",
    "type": "transfer",
    "status": "pending",
    "depositAddress": "TDrhiGeJ11zNStTLhcJt4CvqSwyUVbHPZR",
    "cryptoAmount": 6.6038,
    "crypto": "USDT",
    "network": "trc20",
    "fiatAmount": 9500,
    "fiatCurrency": "NGN",
    "transactionUsd": 6.60,
    "rate": 1439.00,
    "charge": {
      "fiat": 500,
      "crypto": 0.3474,
      "usd": 0.35
    },
    "expiresAt": "2024-03-03T11:00:00.000Z"
  }
}

Example: Create Gift

POST /v1/payments
{
  "type": "gift",
  "fiatAmount": 5000,
  "fiatCurrency": "NGN",
  "crypto": "BTC",
  "network": "bitcoin",
  "payer": {
    "chatId": "7389201648"
  },
  "metadata": {
    "message": "Happy Birthday!"
  }
}

Response:

{
  "success": true,
  "payment": {
    "reference": "2S-GIFT01",
    "type": "gift",
    "status": "pending",
    "depositAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "cryptoAmount": 0.0000328,
    "crypto": "BTC",
    "network": "bitcoin",
    "fiatAmount": 5000,
    "fiatCurrency": "NGN",
    "transactionUsd": 3.09,
    "rate": 1620.5,
    "charge": {
      "fiat": 0,
      "crypto": 0.00000033,
      "usd": 0.05
    },
    "expiresAt": "2024-03-03T14:00:00.000Z"
  }
}

Example: Create Request (Deferred Crypto)

When creating a request, you can omit crypto and network. The payer will choose when fulfilling.

POST /v1/payments
{
  "type": "request",
  "fiatAmount": 25000,
  "fiatCurrency": "NGN",
  "receiver": {
    "bankCode": "044",
    "accountNumber": "0012345678"
  },
  "metadata": {
    "invoiceId": "INV-2024-001"
  }
}

Response:

{
  "success": true,
  "payment": {
    "id": "pay_reqABC789",
    "reference": "2S-REQ001",
    "type": "request",
    "status": "created",
    "fiatAmount": 25000,
    "fiatCurrency": "NGN"
  }
}

Note: No depositAddress, crypto, or cryptoAmount yet - these are set when fulfilled.

---