Skip to main content
GET
Retrieve Onboarding Data

Overview

Retrieves the complete onboarding data for a merchant using the onboarding reference number. This endpoint returns all information submitted during the onboarding process, including business details, representatives, bank accounts, and current approval status.
Use case: Check the status of a merchant’s onboarding application and retrieve all submitted information for review or updates.

Authentication

This endpoint requires JWT Bearer Token authentication.
Authorization Required: The authenticated user must be the owner of the onboarding record. Only the user who created the onboarding record can retrieve it.

Onboarding Status Flow

1

NEW

Merchant has completed the onboarding form and submitted it for initial review. Awaiting admin approval.
2

DECLINED (Optional)

Admin reviewed the application and declined it. The declinedReason field contains the reason for rejection. Merchant needs to update their information.
3

PENDING (Optional)

Merchant has updated their form after being declined and resubmitted for review. Awaiting admin re-approval.
4

APPROVED

Admin has approved the merchant’s onboarding application. Merchant can now process transactions.

Bank Account Masking

Security Feature: Bank account numbers are masked for security based on user roles.
Full account numbers visible to:
  • The account that owns the record
  • The account owner (authenticated user who created the onboarding record)
Other users see: ********1234 (only last 4 digits visible)

Use Cases

Check Application Status

Monitor the approval status of your onboarding application

Review Submitted Data

Verify all information submitted during onboarding

Handle Declined Applications

Check the decline reason and prepare updated information

Retrieve for Updates

Get current data before submitting corrections or updates

Troubleshooting

Error: Onboarding reference number mismatchCause: You’re trying to access an onboarding record that doesn’t belong to your accountSolution:
  • Verify you’re using the correct JWT token for the account that created this onboarding record
  • Each onboarding record can only be accessed by the account that created it Access is limited to records associated with your authenticated account.
Error: Invalid onboarding reference number formatSolution:
  • Ensure the reference number is a valid UUID v4 format
  • Example valid format: 550e8400-e29b-41d4-a716-446655440000
  • Check for extra spaces or incorrect characters
Error: Onboarding record does not existPossible Causes:
  • The reference number is incorrect
  • The onboarding record was deleted
  • You’re using a sandbox reference number in production (or vice versa)
Solution:
  • Double-check the reference number
  • Verify you’re using the correct environment (sandbox vs production)

Next Steps

Onboard Merchant

Create a new merchant onboarding record

Create Account

Create an account before onboarding

Authentication Guide

Learn about JWT token authentication

Error Handling

Handle API errors properly

Authorizations

Authorization
string
header
required

JWT Bearer token authentication

Path Parameters

refNo
string<uuid>
required

The onboarding reference number (UUID v4 format)

Response

Onboarding data retrieved successfully

onboardingStatus
enum<string>
Available options:
NEW,
PENDING,
APPROVED,
DECLINED
onboardingReferenceNumber
string<uuid>
merchantName
string
businessHandle
string
modeOfPayments
string[]
currency
string
tin
string
industry
string
serviceDescription
string
isBrickAndMortarStore
boolean
address
object
representatives
object
banks
object[]
dateCreated
string<date-time>
dateUpdated
string<date-time> | null
declinedReason
string | null