Validate a recipient

Checks that a recipient’s account exists and resolves its registered name, so you can show a confirmation screen before creating an order. Bank accounts are hard-validated; mobile, till, and paybill lookups are best-effort and may return no name even for a valid number.

Endpoint

POST https://merchant.minisend.xyz/api/offramp/validate-account

Authorization: Bearer ms_live_your_key_here

Requires the offramp scope.

Body

currency

string

required

KES, NGN, GHS, or UGX. Determines which recipient fields are required.

recipient

object

required

Recipient shape per method. See recipients.

Example

curl -X POST https://merchant.minisend.xyz/api/offramp/validate-account \
  -H "Authorization: Bearer ms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "recipient": {
      "account_name": "Chidi Okafor",
      "institution": "GTBINGLA",
      "account_number": "0123456789"
    }
  }'

const res = await fetch('https://merchant.minisend.xyz/api/offramp/validate-account', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ms_live_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    currency: 'NGN',
    recipient: {
      account_name: 'Chidi Okafor',
      institution: 'GTBINGLA',
      account_number: '0123456789',
    },
  }),
});

const { valid, recipient_name } = await res.json();

Response (200)

{
  "valid": true,
  "recipient_name": "CHIDI OKAFOR"
}

valid

boolean

required

The account exists and can receive payouts.

recipient_name

string

required

The registered name, or null when the account is valid but the name could not be resolved (common for mobile numbers). Show it to your user before they confirm the payout.

Invalid account (422)

{
  "valid": false,
  "error": "bank account validation failed — account may not exist"
}

Errors

Status	Meaning
`400`	Unsupported currency or malformed recipient
`403`	Key lacks the `offramp` scope or off-ramp is not enabled on your account
`422`	Account failed validation. Returns `valid: false` with an `error` message

​Endpoint

​Body

​Example

​Response (200)

​Invalid account (422)

​Errors

Endpoint

Body

Example

Response (200)

Invalid account (422)

Errors