{"info":{"_postman_id":"9ff096d2-310e-48f9-88ce-16bd5c20c621","name":"OmniPay API Reference","description":"

OmniPay provides customer verification, wallet access, and payment collection through dynamic virtual accounts.

\n

KYC is the entry point. After a retailer completes verification, the kyconboarding.completed webhook returns:

\n\n

KYC onboarding

\n

OmniPay KYC is available for web and React Native.

\n

Create a KYC session

\n

Call Create or resume KYC session when the retailer starts verification. If the response status is active, render Kyc.Onboarding with the returned token. Reuse the same customer details to resume an unfinished session.

\n

The SDK can request a replacement token after the initial token expires. The getToken callback must create or resume the same session and resolve with the new token.

\n

React web

\n
npm install @omniretail/kyc-react-sdk\n
\n
import {Kyc} from '@omniretail/kyc-react-sdk';\nimport '@omniretail/kyc-react-sdk/styles.css';\n\n<Kyc.Onboarding\n  env=\"dev\"\n  token={kycToken}\n  getToken={refreshKycToken}\n  primaryColor=\"#A682FF\"\n  onComplete={refreshCustomerStatus}\n  onClose={() => history.back()}\n  onTokenExpired={restartVerification}\n  onError={error => reportErrorCode(error.code)}\n/>\n
\n

React Native

\n
npm install @omniretail/kyc-sdk \\\n  react-native-webview react-native-safe-area-context \\\n  react-native-image-picker react-native-geolocation-service react-native-device-info \\\n  @react-native-async-storage/async-storage @react-native-documents/picker \\\n  @react-native-community/datetimepicker\n
\n
import {Kyc} from '@omniretail/kyc-sdk';\n\n<Kyc.Onboarding\n  env=\"dev\"\n  token={kycToken}\n  getToken={refreshKycToken}\n  primaryColor=\"#A682FF\"\n  onComplete={refreshCustomerStatus}\n  onClose={closeVerification}\n  onTokenExpired={restartVerification}\n  onError={error => reportErrorCode(error.code)}\n/>\n
\n

Session props

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropRequiredDescription
envyesdev or prod. Must match the KYC session environment.
tokenyesRestricted token returned for an active KYC session.
getTokennoAsync callback that resolves with a fresh token for the same session.
primaryColornoThree- or six-digit hex colour. Defaults to #A682FF.
onCompleteyesCalled when the retailer reaches the end of the KYC journey.
onCloseyesCalled when the retailer closes KYC.
onTokenExpirednoCalled when the SDK cannot refresh an expired token.
onErrornoReceives the SDK error code and message.
\n

Treat the kyconboarding.completed webhook as the final confirmation of verification.

\n

React Native applications must declare camera, photo-library, foreground-location, and internet permissions. Run CocoaPods on iOS and rebuild the application after installing the native dependencies.

\n

Wallet SDK

\n

Display a retailer's OmniPay wallet in a React Native application. The Wallet component opens in a native modal.

\n

Create a session

\n

Create a Wallet SDK session with the customerRef received in the KYC completion webhook. The response contains data.sessionId, which is passed to the component. Create a new session when it expires.

\n

Install

\n
npm install @omniretail/wallet-sdk \\\n  react-native-webview react-native-device-info \\\n  react-native-select-contact react-native-share\n
\n

Run CocoaPods on iOS, then rebuild the application.

\n
npx pod-install\n
\n

Render the wallet

\n
import {useState} from 'react';\nimport {Button} from 'react-native';\nimport {Wallet} from '@omniretail/wallet-sdk';\n\nconst OMNIPAY_PUBLIC_KEY =\n  'OMNIPUBKEY_FLX4HPQKKX124QBVQIKAAKSUNX4FIIXC';\n\nexport function WalletScreen({customerRef, sessionId}) {\n  const [walletOpen, setWalletOpen] = useState(false);\n\n  return (\n    <>\n      <Button title=\"Open wallet\" onPress={() => setWalletOpen(true)} />\n\n      {walletOpen ? (\n        <Wallet\n          env=\"dev\"\n          publicKey={OMNIPAY_PUBLIC_KEY}\n          customerRef={customerRef}\n          sessionId={sessionId}\n          features={{\n            airtimeAndData: true,\n            bills: true,\n            paylater: true,\n            transfers: true,\n          }}\n          onClose={() => setWalletOpen(false)}\n        />\n      ) : null}\n    </>\n  );\n}\n
\n

Props

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropRequiredDescription
envyesdev or prod. Must match the session environment.
publicKeyyesPublic key for the selected environment.
customerRefyesValue from data.customerRef in the KYC completion webhook.
sessionIdyesValue from data.sessionId in the Wallet SDK session response.
onCloseyesCalled after the wallet modal closes.
primaryColornoThree- or six-digit hex colour. Defaults to #A682FF.
featuresnoControls access to airtime and data, bills, Paylater, and transfers.
onErrornoReceives the SDK error code and message.
\n

Collect payment with a dynamic virtual account

\n

Collect a bank transfer for an order with a single-use dynamic virtual account. The order identifies the retailer's wallet, and the account details are presented to the customer making the payment.

\n

Create a payment

\n
    \n
  1. Create an order for the payment amount and set metadata.receiverWalletId to the retailer's walletId.
    2. \n
  2. Create a dynamic virtual account with the same orderId and amount.
    3. \n
  3. Show the returned bank name, account number, account name, amount, and expiry time.
    4. \n
  4. Confirm payment only after receiving orderpayment.successful.
    5. \n
\n

Amounts are sent in kobo. Both requests require apiKey and IdempotencyKey headers. Use a new idempotency key for each operation and retain it when retrying that operation.

\n

Environments

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EnvironmentAPI base URLSDK env
Developmenthttps://api-dev.ompy.ngdev
Productionhttps://api.ompy.ngprod
\n

Credentials and SDK sessions are specific to an environment.

\n

Test credentials

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CredentialValue
API keyxrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6
Wallet SDK public keyOMNIPUBKEY_FLX4HPQKKX124QBVQIKAAKSUNX4FIIXC
\n

These credentials are valid in the development environment. Production credentials are issued during go-live.

\n

Authentication

\n

Authenticate API requests with the apiKey header. API keys are secret and must never be included in web or mobile applications.

\n
apiKey: xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6\n
\n

Amounts

\n

Amounts are integer values in kobo. For example, NGN 37,000.00 is 3700000.

\n

Idempotent requests

\n

Order and dynamic-account requests require an IdempotencyKey header. Generate a value between 8 and 50 characters for a new request, and retain it for retries of that request. A different operation requires a new value.

\n

Webhooks

\n

Register an HTTPS webhook URL with OmniPay before going live.

\n

Each webhook includes a signature header containing the hexadecimal HMAC-SHA512 signature of the raw request body. Compute the signature with the OmniPay API key and compare it before parsing the JSON.

\n
import crypto from 'node:crypto';\n\nfunction verifyOmniPaySignature(rawBody, signature, apiKey) {\n  if (!signature || !/^[0-9a-f]+$/i.test(signature)) return false;\n\n  const expected = crypto\n    .createHmac('sha512', apiKey)\n    .update(rawBody)\n    .digest();\n  const received = Buffer.from(signature, 'hex');\n\n  return received.length === expected.length &&\n    crypto.timingSafeEqual(received, expected);\n}\n\napp.post(\n  '/webhooks/omnipay',\n  express.raw({type: 'application/json'}),\n  async (req, res) => {\n    if (!verifyOmniPaySignature(\n      req.body,\n      req.get('signature'),\n      process.env.OMNIPAY_API_KEY,\n    )) {\n      return res.sendStatus(401);\n    }\n\n    const event = JSON.parse(req.body.toString('utf8'));\n    await processOmniPayEvent(event);\n    return res.sendStatus(200);\n  },\n);\n
\n

A webhook can be delivered more than once. Store the event before returning HTTP 200, and make processing idempotent using referenceId or transactionId.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"56708741","collectionId":"9ff096d2-310e-48f9-88ce-16bd5c20c621","publishedId":"2sBY4Tpctg","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-07-31T18:56:55.000Z"},"item":[{"name":"KYC onboarding","item":[{"name":"Create or resume KYC session","event":[{"listen":"test","script":{"type":"text/javascript","exec":["const body = pm.response.json();","if (body.token) pm.collectionVariables.set('kycToken', body.token);","pm.test('Session is active or completed', () => pm.expect(['active', 'completed']).to.include(body.status));","if (body.status === 'active') pm.test('Restricted token returned', () => pm.expect(body.token).to.be.a('string').and.not.empty);"]}}],"id":"a3ce8f14-5d83-41f9-9bf0-f8d9a6041dcf","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6","description":"

Development API key. Keep it out of client code.

\n"}],"body":{"mode":"raw","raw":"{\n \"referenceId\": \"customer_1001\",\n \"phoneNumber\": \"08012345678\",\n \"profileType\": \"secondary\",\n \"emailAddress\": \"customer@example.com\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/kycservice/session","description":"

Creates a KYC session or returns the state of an existing session.

\n

Supply the same referenceId, phoneNumber, and emailAddress to resume an unfinished session.

\n

Parameters

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
referenceIdstringyesUnique, stable customer identifier.
phoneNumberstringyesRetailer's phone number.
profileTypestringyessecondary for a retailer.
emailAddressstringyesRetailer's email address.
\n

Returns

\n

An active session returns status, token, and expiresAt. Pass token to Kyc.Onboarding.

\n

A completed session returns status and identityNumber. Wait for the completion webhook to obtain customerRef and walletId.

\n","urlObject":{"path":["kycservice","session"],"host":["https://api-dev.ompy.ng"],"query":[],"variable":[]}},"response":[{"id":"a376e90c-81b1-446e-8c0e-aa7d962b6fc5","name":"200 - Active session","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6","description":"Development API key. Keep it out of client code."}],"body":{"mode":"raw","raw":"{\n \"referenceId\": \"customer_1001\",\n \"phoneNumber\": \"08012345678\",\n \"profileType\": \"secondary\",\n \"emailAddress\": \"customer@example.com\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/kycservice/session","description":"Creates a KYC session or returns the state of an existing session.\n\nSupply the same `referenceId`, `phoneNumber`, and `emailAddress` to resume an unfinished session.\n\n## Parameters\n\n| Field | Type | Required | Description |\n|---|---|---:|---|\n| `referenceId` | string | yes | Unique, stable customer identifier. |\n| `phoneNumber` | string | yes | Retailer's phone number. |\n| `profileType` | string | yes | `secondary` for a retailer. |\n| `emailAddress` | string | yes | Retailer's email address. |\n\n## Returns\n\nAn active session returns `status`, `token`, and `expiresAt`. Pass `token` to `Kyc.Onboarding`.\n\nA completed session returns `status` and `identityNumber`. Wait for the completion webhook to obtain `customerRef` and `walletId`."},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"active\",\n \"token\": \"restricted-kyc-token\",\n \"expiresAt\": \"2026-07-31T18:30:00Z\",\n \"profileType\": \"secondary\"\n}"},{"id":"cf4d208b-7e65-4c8e-93a4-e757d6cd24da","name":"200 - KYC already completed","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6","description":"Development API key. Keep it out of client code."}],"body":{"mode":"raw","raw":"{\n \"referenceId\": \"customer_1001\",\n \"phoneNumber\": \"08012345678\",\n \"profileType\": \"secondary\",\n \"emailAddress\": \"customer@example.com\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/kycservice/session","description":"Creates a KYC session or returns the state of an existing session.\n\nSupply the same `referenceId`, `phoneNumber`, and `emailAddress` to resume an unfinished session.\n\n## Parameters\n\n| Field | Type | Required | Description |\n|---|---|---:|---|\n| `referenceId` | string | yes | Unique, stable customer identifier. |\n| `phoneNumber` | string | yes | Retailer's phone number. |\n| `profileType` | string | yes | `secondary` for a retailer. |\n| `emailAddress` | string | yes | Retailer's email address. |\n\n## Returns\n\nAn active session returns `status`, `token`, and `expiresAt`. Pass `token` to `Kyc.Onboarding`.\n\nA completed session returns `status` and `identityNumber`. Wait for the completion webhook to obtain `customerRef` and `walletId`."},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"completed\",\n \"identityNumber\": \"291fc12b5046c93dadc45d5eaa157624aa071b429a0d27ed8df6ce0b6cb9699e\",\n \"profileType\": \"secondary\"\n}"},{"id":"75feb89d-6c13-444f-a3cb-ce3850588161","name":"409 - Reference conflicts with existing details","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6","description":"Development API key. Keep it out of client code."}],"body":{"mode":"raw","raw":"{\n \"referenceId\": \"customer_1001\",\n \"phoneNumber\": \"08012345678\",\n \"profileType\": \"secondary\",\n \"emailAddress\": \"customer@example.com\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/kycservice/session","description":"Creates a KYC session or returns the state of an existing session.\n\nSupply the same `referenceId`, `phoneNumber`, and `emailAddress` to resume an unfinished session.\n\n## Parameters\n\n| Field | Type | Required | Description |\n|---|---|---:|---|\n| `referenceId` | string | yes | Unique, stable customer identifier. |\n| `phoneNumber` | string | yes | Retailer's phone number. |\n| `profileType` | string | yes | `secondary` for a retailer. |\n| `emailAddress` | string | yes | Retailer's email address. |\n\n## Returns\n\nAn active session returns `status`, `token`, and `expiresAt`. Pass `token` to `Kyc.Onboarding`.\n\nA completed session returns `status` and `identityNumber`. Wait for the completion webhook to obtain `customerRef` and `walletId`."},"status":"Conflict","code":409,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": \"session_conflict\",\n \"message\": \"This verification session was started for different account details.\"\n}"}],"_postman_id":"a3ce8f14-5d83-41f9-9bf0-f8d9a6041dcf"},{"name":"[WEBHOOK] KYC completed and wallet created","id":"8c9c0562-d467-4c0e-84d7-8a737da098dd","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"signature","value":"","description":"

HMAC-SHA512 signature of the webhook payload, created with the OmniPay API key.

\n"}],"body":{"mode":"raw","raw":"{\n \"event\": \"kyconboarding.completed\",\n \"data\": {\n \"referenceId\": \"customer_1001\",\n \"identityNumber\": \"291fc12b5046c93dadc45d5eaa157624aa071b429a0d27ed8df6ce0b6cb9699e\",\n \"createdAt\": \"2026-07-31T17:30:00Z\",\n \"customerRef\": \"customer-ref-from-omnipay\",\n \"walletId\": \"wallet-id-from-omnipay\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://example.com/webhooks/omnipay","description":"

Occurs after KYC is completed and the retailer's wallet is ready. Verify the webhook signature before processing the payload.

\n

Event data

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldDescription
data.referenceIdCustomer identifier supplied when the KYC session was created.
data.identityNumberOmniPay identity identifier.
data.createdAtTime the event was created.
data.customerRefCustomer reference used to create Wallet SDK sessions.
data.walletIdWallet identifier used as the payment destination on an order.
\n

Match the event to the customer using data.referenceId, store customerRef and walletId, then return HTTP 200. Processing must be idempotent because the event can be delivered more than once.

\n","urlObject":{"host":["https://example.com/webhooks/omnipay"],"query":[],"variable":[]}},"response":[{"id":"a1905b7c-5681-4c27-a0ea-4a0b6221870d","name":"200 - Acknowledged","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"signature","value":"","description":"HMAC-SHA512 signature of the webhook payload, created with the OmniPay API key."}],"body":{"mode":"raw","raw":"{\n \"event\": \"kyconboarding.completed\",\n \"data\": {\n \"referenceId\": \"customer_1001\",\n \"identityNumber\": \"291fc12b5046c93dadc45d5eaa157624aa071b429a0d27ed8df6ce0b6cb9699e\",\n \"createdAt\": \"2026-07-31T17:30:00Z\",\n \"customerRef\": \"customer-ref-from-omnipay\",\n \"walletId\": \"wallet-id-from-omnipay\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://example.com/webhooks/omnipay","description":"Occurs after KYC is completed and the retailer's wallet is ready. Verify the webhook signature before processing the payload.\n\n## Event data\n\n| Field | Description |\n|---|---|\n| `data.referenceId` | Customer identifier supplied when the KYC session was created. |\n| `data.identityNumber` | OmniPay identity identifier. |\n| `data.createdAt` | Time the event was created. |\n| `data.customerRef` | Customer reference used to create Wallet SDK sessions. |\n| `data.walletId` | Wallet identifier used as the payment destination on an order. |\n\nMatch the event to the customer using `data.referenceId`, store `customerRef` and `walletId`, then return HTTP `200`. Processing must be idempotent because the event can be delivered more than once."},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"statusCode\": 200,\n \"message\": \"Success\"\n}"}],"_postman_id":"8c9c0562-d467-4c0e-84d7-8a737da098dd"}],"id":"89f726a1-e6e0-454d-b673-b4a7002f3781","_postman_id":"89f726a1-e6e0-454d-b673-b4a7002f3781","description":""},{"name":"Wallet SDK","item":[{"name":"Create Wallet SDK session","event":[{"listen":"test","script":{"type":"text/javascript","exec":["const body = pm.response.json();","if (body.data?.sessionId) pm.collectionVariables.set('walletSessionId', body.data.sessionId);","pm.test('Wallet SDK session created', () => {"," pm.expect(pm.response.code).to.eql(200);"," pm.expect(body.error).to.eql(false);"," pm.expect(body.data.sessionId).to.be.a('string').and.not.empty;","});"]}}],"id":"74b5e7b0-636e-4de0-b853-3f44b1be19d4","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6","description":"

Development API key. Keep it out of client code.

\n"}],"body":{"mode":"raw","raw":"{\n \"customerRef\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/sdk/createSession","description":"

Creates a short-lived session for the React Native Wallet SDK.

\n

Parameters

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
customerRefstringyesValue from data.customerRef in the KYC completion webhook.
\n

Returns

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldDescription
data.sessionIdSession identifier passed to the Wallet component.
data.expiresInNumber of seconds before the session expires.
data.sessionTokenOmniPay session credential. Keep this value out of the mobile application.
\n

The Wallet component requires data.sessionId and customerRef.

\n","urlObject":{"path":["sdk","createSession"],"host":["https://api-dev.ompy.ng"],"query":[],"variable":[]}},"response":[{"id":"724133c7-6c7d-452c-9805-205ad9e4487b","name":"200 - Wallet SDK session created","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6","description":"Development API key. Keep it out of client code."}],"body":{"mode":"raw","raw":"{\n \"customerRef\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/sdk/createSession","description":"Creates a short-lived session for the React Native Wallet SDK.\n\n## Parameters\n\n| Field | Type | Required | Description |\n|---|---|---:|---|\n| `customerRef` | string | yes | Value from `data.customerRef` in the KYC completion webhook. |\n\n## Returns\n\n| Field | Description |\n|---|---|\n| `data.sessionId` | Session identifier passed to the `Wallet` component. |\n| `data.expiresIn` | Number of seconds before the session expires. |\n| `data.sessionToken` | OmniPay session credential. Keep this value out of the mobile application. |\n\nThe `Wallet` component requires `data.sessionId` and `customerRef`."},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": false,\n \"message\": \"Session Started Successfully\",\n \"data\": {\n \"sessionId\": \"4354d26b1b5ac968e349ef25bad47dc63c622cc55955b18d0224f8ac804ac920\",\n \"expiresIn\": 259200,\n \"sessionToken\": \"wallet-sdk-session-token\"\n }\n}"},{"id":"65ab51e0-a5b4-4c90-8803-250d0cdc903f","name":"400 - Invalid customer reference","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6","description":"Development API key. Keep it out of client code."}],"body":{"mode":"raw","raw":"{\n \"customerRef\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/sdk/createSession","description":"Creates a short-lived session for the React Native Wallet SDK.\n\n## Parameters\n\n| Field | Type | Required | Description |\n|---|---|---:|---|\n| `customerRef` | string | yes | Value from `data.customerRef` in the KYC completion webhook. |\n\n## Returns\n\n| Field | Description |\n|---|---|\n| `data.sessionId` | Session identifier passed to the `Wallet` component. |\n| `data.expiresIn` | Number of seconds before the session expires. |\n| `data.sessionToken` | OmniPay session credential. Keep this value out of the mobile application. |\n\nThe `Wallet` component requires `data.sessionId` and `customerRef`."},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": true,\n \"message\": \"Invalid Customer Ref\",\n \"data\": {\n \"sessionId\": null,\n \"expiresIn\": 0,\n \"sessionToken\": null\n }\n}"}],"_postman_id":"74b5e7b0-636e-4de0-b853-3f44b1be19d4"}],"id":"355daad6-f76e-43f4-b5e6-d774da2a7054","_postman_id":"355daad6-f76e-43f4-b5e6-d774da2a7054","description":""},{"name":"Collect payment with a dynamic virtual account","item":[{"name":"Create order","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":["if (!pm.collectionVariables.get('orderIdempotencyKey')) {"," pm.collectionVariables.set('orderIdempotencyKey', pm.variables.replaceIn('8369d315-7f09-4a4e-9957-b76b69b1bfb1'));","}"]}},{"listen":"test","script":{"type":"text/javascript","exec":["pm.test('Order accepted', () => pm.expect(pm.response.code).to.be.oneOf([200, 201]));"]}}],"id":"63454075-1d10-4271-9c98-31b5939cd46e","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6"},{"key":"IdempotencyKey","value":""}],"body":{"mode":"raw","raw":"{\n \"orderId\": \"SO_1001\",\n \"orderAmount\": 3700000,\n \"metadata\": \"{\\\"receiverWalletId\\\":\\\"\\\"}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/Order/CreateOrder","description":"

Creates an order for a payment to the retailer's wallet.

\n

Parameters

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
orderIdstringyesSO_{order id on their system}. For example, order 1001 is SO_1001. Must be unique.
orderAmountintegeryesPayment amount in kobo. For example, NGN 5,000.00 is 500000.
metadatastringyesJSON string containing receiverWalletId, set to the retailer's walletId.
\n

metadata is JSON encoded as a string. Escape its quotation marks as shown in the request body.

\n

Returns

\n

Returns HTTP 201 when the order is created. Use the same orderId and orderAmount to create the dynamic virtual account.

\n","urlObject":{"path":["Order","CreateOrder"],"host":["https://api-dev.ompy.ng"],"query":[],"variable":[]}},"response":[{"id":"3b678c4c-628c-4997-acd6-983aa2ab300f","name":"201 - Order created","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6"},{"key":"IdempotencyKey","value":""}],"body":{"mode":"raw","raw":"{\n \"orderId\": \"SO_1001\",\n \"orderAmount\": 3700000,\n \"metadata\": \"{\\\"receiverWalletId\\\":\\\"\\\"}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/Order/CreateOrder","description":"Creates an order for a payment to the retailer's wallet.\n\n## Parameters\n\n| Field | Type | Required | Description |\n|---|---|---:|---|\n| `orderId` | string | yes | `SO_{order id on their system}`. For example, order `1001` is `SO_1001`. Must be unique. |\n| `orderAmount` | integer | yes | Payment amount in kobo. For example, NGN 5,000.00 is `500000`. |\n| `metadata` | string | yes | JSON string containing `receiverWalletId`, set to the retailer's `walletId`. |\n\n`metadata` is JSON encoded as a string. Escape its quotation marks as shown in the request body.\n\n## Returns\n\nReturns HTTP `201` when the order is created. Use the same `orderId` and `orderAmount` to create the dynamic virtual account."},"status":"Created","code":201,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": false,\n \"message\": \"Order created successfully\",\n \"data\": null\n}"},{"id":"b48d654a-b306-46b3-bae9-9d632d3202ea","name":"400 - Validation error","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6"},{"key":"IdempotencyKey","value":""}],"body":{"mode":"raw","raw":"{\n \"orderId\": \"SO_1001\",\n \"orderAmount\": 3700000,\n \"metadata\": \"{\\\"receiverWalletId\\\":\\\"\\\"}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/Order/CreateOrder","description":"Creates an order for a payment to the retailer's wallet.\n\n## Parameters\n\n| Field | Type | Required | Description |\n|---|---|---:|---|\n| `orderId` | string | yes | `SO_{order id on their system}`. For example, order `1001` is `SO_1001`. Must be unique. |\n| `orderAmount` | integer | yes | Payment amount in kobo. For example, NGN 5,000.00 is `500000`. |\n| `metadata` | string | yes | JSON string containing `receiverWalletId`, set to the retailer's `walletId`. |\n\n`metadata` is JSON encoded as a string. Escape its quotation marks as shown in the request body.\n\n## Returns\n\nReturns HTTP `201` when the order is created. Use the same `orderId` and `orderAmount` to create the dynamic virtual account."},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": true,\n \"message\": \"Order amount should be greater than 0\",\n \"data\": null\n}"}],"_postman_id":"63454075-1d10-4271-9c98-31b5939cd46e"},{"name":"Create dynamic virtual account","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":["if (!pm.collectionVariables.get('dynamicAccountIdempotencyKey')) {"," pm.collectionVariables.set('dynamicAccountIdempotencyKey', pm.variables.replaceIn('4d8debf7-ee5d-4227-9cf1-7d97a304c8ac'));","}"]}},{"listen":"test","script":{"type":"text/javascript","exec":["const body = pm.response.json();","pm.test('Dynamic account created', () => {"," pm.expect(pm.response.code).to.eql(200);"," pm.expect(body.error).to.eql(false);"," pm.expect(body.data.accountNumber).to.be.a('string').and.not.empty;"," pm.expect(body.data.bankName).to.eql('Victory Mfb');","});"]}}],"id":"390b7466-be77-42c6-98e2-0951e3bb998e","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6"},{"key":"IdempotencyKey","value":""}],"body":{"mode":"raw","raw":"{\n \"amount\": 3700000,\n \"orderId\": \"SO_1001\",\n \"accountName\": \"Ada Customer\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/Wallet/CreateDynamicAccount","description":"

Creates a temporary bank account for an existing order.

\n

Parameters

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
amountintegeryesExact order amount in kobo.
orderIdstringyesorderId of the existing order.
accountNamestringyesAccount name shown to the customer. Accepts letters and spaces.
\n

amount must equal the order's orderAmount.

\n

Returns

\n

The response contains accountName, accountNumber, bankName, bankCode, referenceId, and expiresIn. The bank is Victory Mfb.

\n

Display the account details with the exact payment amount and expiry time. Stop accepting payment to the account after it expires. Account creation does not confirm that the order has been paid.

\n","urlObject":{"path":["Wallet","CreateDynamicAccount"],"host":["https://api-dev.ompy.ng"],"query":[],"variable":[]}},"response":[{"id":"61630e18-05b6-442a-bceb-dfb7f789cbdf","name":"200 - Dynamic account ready","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6"},{"key":"IdempotencyKey","value":""}],"body":{"mode":"raw","raw":"{\n \"amount\": 3700000,\n \"orderId\": \"SO_1001\",\n \"accountName\": \"Ada Customer\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/Wallet/CreateDynamicAccount","description":"Creates a temporary bank account for an existing order.\n\n## Parameters\n\n| Field | Type | Required | Description |\n|---|---|---:|---|\n| `amount` | integer | yes | Exact order amount in kobo. |\n| `orderId` | string | yes | `orderId` of the existing order. |\n| `accountName` | string | yes | Account name shown to the customer. Accepts letters and spaces. |\n\n`amount` must equal the order's `orderAmount`.\n\n## Returns\n\nThe response contains `accountName`, `accountNumber`, `bankName`, `bankCode`, `referenceId`, and `expiresIn`. The bank is `Victory Mfb`.\n\nDisplay the account details with the exact payment amount and expiry time. Stop accepting payment to the account after it expires. Account creation does not confirm that the order has been paid."},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": false,\n \"message\": \"Dynamic account created successfully\",\n \"data\": {\n \"accountNumber\": \"0123456789\",\n \"bankCode\": \"090813\",\n \"bankName\": \"Victory Mfb\",\n \"referenceId\": \"orderIdSO_1001\",\n \"accountName\": \"Ada Customer\",\n \"expiresIn\": 3590.0\n }\n}"},{"id":"a7dfbc6a-33e3-4977-b96d-2cfbfe54c504","name":"400 - Order missing or already paid","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6"},{"key":"IdempotencyKey","value":""}],"body":{"mode":"raw","raw":"{\n \"amount\": 3700000,\n \"orderId\": \"SO_1001\",\n \"accountName\": \"Ada Customer\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-dev.ompy.ng/Wallet/CreateDynamicAccount","description":"Creates a temporary bank account for an existing order.\n\n## Parameters\n\n| Field | Type | Required | Description |\n|---|---|---:|---|\n| `amount` | integer | yes | Exact order amount in kobo. |\n| `orderId` | string | yes | `orderId` of the existing order. |\n| `accountName` | string | yes | Account name shown to the customer. Accepts letters and spaces. |\n\n`amount` must equal the order's `orderAmount`.\n\n## Returns\n\nThe response contains `accountName`, `accountNumber`, `bankName`, `bankCode`, `referenceId`, and `expiresIn`. The bank is `Victory Mfb`.\n\nDisplay the account details with the exact payment amount and expiry time. Stop accepting payment to the account after it expires. Account creation does not confirm that the order has been paid."},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": true,\n \"message\": \"Order already paid for\",\n \"data\": null\n}"}],"_postman_id":"390b7466-be77-42c6-98e2-0951e3bb998e"},{"name":"[WEBHOOK] Order payment successful","id":"b48b9be1-0e22-41d5-bd22-2a4bd4d9743e","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"signature","value":"","description":"

HMAC-SHA512 signature of the webhook payload, created with the OmniPay API key.

\n"}],"body":{"mode":"raw","raw":"{\n \"event\": \"orderpayment.successful\",\n \"data\": {\n \"customerRef\": null,\n \"userRef\": null,\n \"walletBalance\": 0,\n \"createdAt\": \"2026-07-31T18:00:00Z\",\n \"walletPayment\": 3700000,\n \"paylaterPayment\": 0,\n \"promoPayment\": 0,\n \"orderValue\": 3700000,\n \"orderId\": \"SO_1001\",\n \"loanId\": null,\n \"transactionId\": \"TRX-OMN-2026-001234\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://example.com/webhooks/omnipay","description":"

Occurs after a bank transfer is confirmed and applied to the order. Verify the webhook signature before processing the payload.

\n

Event data

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldDescription
data.orderIdOrder identifier supplied when the order was created.
data.orderValueOrder amount in kobo.
data.walletPaymentAmount credited to the retailer's wallet in kobo.
data.transactionIdUnique OmniPay transaction identifier.
data.createdAtTime the event was created.
\n

Find the order by data.orderId, verify the amounts, store data.transactionId, and mark the order as paid. Return HTTP 200 after the update is committed. If transactionId has already been processed, return HTTP 200 without applying the payment again.

\n","urlObject":{"host":["https://example.com/webhooks/omnipay"],"query":[],"variable":[]}},"response":[{"id":"2ca49433-cf76-40a4-8da4-778f1569151b","name":"200 - Acknowledged","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"signature","value":"","description":"HMAC-SHA512 signature of the webhook payload, created with the OmniPay API key."}],"body":{"mode":"raw","raw":"{\n \"event\": \"orderpayment.successful\",\n \"data\": {\n \"customerRef\": null,\n \"userRef\": null,\n \"walletBalance\": 0,\n \"createdAt\": \"2026-07-31T18:00:00Z\",\n \"walletPayment\": 3700000,\n \"paylaterPayment\": 0,\n \"promoPayment\": 0,\n \"orderValue\": 3700000,\n \"orderId\": \"SO_1001\",\n \"loanId\": null,\n \"transactionId\": \"TRX-OMN-2026-001234\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://example.com/webhooks/omnipay","description":"Occurs after a bank transfer is confirmed and applied to the order. Verify the webhook signature before processing the payload.\n\n## Event data\n\n| Field | Description |\n|---|---|\n| `data.orderId` | Order identifier supplied when the order was created. |\n| `data.orderValue` | Order amount in kobo. |\n| `data.walletPayment` | Amount credited to the retailer's wallet in kobo. |\n| `data.transactionId` | Unique OmniPay transaction identifier. |\n| `data.createdAt` | Time the event was created. |\n\nFind the order by `data.orderId`, verify the amounts, store `data.transactionId`, and mark the order as paid. Return HTTP `200` after the update is committed. If `transactionId` has already been processed, return HTTP `200` without applying the payment again."},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"statusCode\": 200,\n \"message\": \"Success\"\n}"}],"_postman_id":"b48b9be1-0e22-41d5-bd22-2a4bd4d9743e"}],"id":"500ba1c8-2aef-46cf-96a8-37ee44fbd3ef","_postman_id":"500ba1c8-2aef-46cf-96a8-37ee44fbd3ef","description":""}],"variable":[{"key":"omniPayApiBaseUrl","value":"https://api-dev.ompy.ng","type":"string","description":"Use https://api.ompy.ng in production."},{"key":"apiKey","value":"xrcQVg90ujKbUwUBytlrrHwxyds17yPo8JbBmK52IOzuLkBZYR26mqW06ZstCTr6","type":"string","description":"Development API key for https://api-dev.ompy.ng."},{"key":"walletPublicKey","value":"OMNIPUBKEY_FLX4HPQKKX124QBVQIKAAKSUNX4FIIXC","type":"string","description":"Development public key for the React Native Wallet SDK."},{"key":"referenceId","value":"customer_1001","type":"string","description":"Stable unique identifier assigned to the customer."},{"key":"phoneNumber","value":"08012345678","type":"string"},{"key":"emailAddress","value":"customer@example.com","type":"string"},{"key":"kycToken","value":"","type":"string","description":"Captured from the KYC session response; pass only this scoped token to Kyc.Onboarding."},{"key":"customerRef","value":"","type":"string","description":"OmniPay customer reference received in the KYC completion webhook."},{"key":"walletSessionId","value":"","type":"string","description":"Captured from the Wallet SDK session response and passed to the Wallet SDK."},{"key":"walletId","value":"","type":"string","description":"OmniPay wallet that receives the order payment."},{"key":"orderId","value":"SO_1001","type":"string","description":"Prefix the existing order ID with SO_; for example, SO_1001."},{"key":"amountKobo","value":"3700000","type":"string","description":"NGN 37,000.00 expressed in kobo."},{"key":"payerDisplayName","value":"Ada Customer","type":"string","description":"Letters and spaces only."},{"key":"orderIdempotencyKey","value":"","type":"string","description":"Idempotency key for order creation."},{"key":"dynamicAccountIdempotencyKey","value":"","type":"string","description":"Idempotency key for dynamic virtual account creation."},{"key":"yourWebhookUrl","value":"https://example.com/webhooks/omnipay","type":"string","description":"HTTPS webhook URL registered with OmniPay."}]}