Africa Fintech FoundryDeveloper Portal
Get API keys
Escrow API

Merchants & sellers

Create and authenticate a merchant, validate its refresh token, and register the sellers who receive escrow payouts.

POST

Create merchant

/api/merchants/Create
Creates the merchant that owns sellers and escrow transactions.
Parameters
merchantNamestringrequiredMerchant name.
emailAddressstring · emailrequiredMerchant email address.
companyPhoneNumberstringrequiredCompany phone number.
settlementPreferenceinteger enumrequiredOne of 1 or 2; meanings are not named in the schema.
settlementAccountNumberstring · 10 digitsrequiredSettlement account number matching ^\d{10}$.
settlementBankNamestringrequiredSettlement bank name.
settlementBankCodestringSettlement bank code.
settlementAccountNamestringrequiredSettlement account name.
allowEscrowToNotifySellersbooleanrequiredWhether Escrow may notify sellers.
// request
{
  "merchantName": "Yaba Threads Ltd",
  "emailAddress": "merchant@example.invalid",
  "companyPhoneNumber": "08000000000",
  "settlementPreference": 1,
  "settlementAccountNumber": "0000000000",
  "settlementBankName": "Access Bank",
  "settlementBankCode": "044",
  "settlementAccountName": "YABA THREADS LTD",
  "allowEscrowToNotifySellers": true
}
POST

Merchant login

/api/merchants/Login
Authenticates a merchant with its username and authentication key.
Parameters
merchantUsernamestring · nullableMerchant username.
merchantAuthKeystring · nullableMerchant authentication key.
// request
{
  "merchantUsername": "yaba-threads",
  "merchantAuthKey": "••••••••"
}
POST

Validate refresh token

/api/merchants/Validate-refresh-token
Submits a merchant refresh token for validation.
Parameters
refreshTokenstring · nullableMerchant refresh token.
// request
{
  "refreshToken": "••••••••"
}
POST

Register seller

/api/merchants/Register-Sellers
Registers a seller and the bank account used for settlement.
Parameters
merchantIdstring · nullableMerchant identifier.
businessNamestringrequiredSeller business name.
businessCategoryinteger enumOne of 1–20; meanings are not named in the schema.
sellerFirstNamestringrequiredSeller first name.
sellerLastNamestringrequiredSeller last name.
sellerEmailAddressstringrequiredSeller email address.
sellerPhoneNumberstringrequiredSeller phone number.
bankNamestringrequiredSettlement bank name.
accountNamestringrequiredSettlement account name.
accountNumberstringrequiredSettlement account number.
bankCodestringrequiredSettlement bank code.
bvnstringrequiredSeller BVN.
rcNumberstring · nullableCompany registration number.
companyTypestring · nullableCompany type.
// request
{
  "merchantId": "MER-0001",
  "businessName": "Emeka Okafor Textiles",
  "businessCategory": 1,
  "sellerFirstName": "Emeka",
  "sellerLastName": "Okafor",
  "sellerEmailAddress": "seller@example.invalid",
  "sellerPhoneNumber": "08000000001",
  "bankName": "Access Bank",
  "accountName": "EMEKA OKAFOR TEXTILES",
  "accountNumber": "0000000001",
  "bankCode": "044",
  "bvn": "00000000000",
  "rcNumber": "RC000000",
  "companyType": "LIMITED LIABILITY COMPANY"
}