# Developers Korapay — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access Korapay's payment infrastructure: initialize checkouts, manage virtual bank accounts and cards, initiate payouts, verify bank accounts, and query transaction history — all via a single API.

**Category:** Finance & Markets | **Website:** [developers.korapay.com/](https://developers.korapay.com/) | **Docs:** [parse.bot/marketplace/21a93a49-b84d-4c8c-ba3c-cec31d781647/developers-korapay-com-api](https://parse.bot/marketplace/21a93a49-b84d-4c8c-ba3c-cec31d781647/developers-korapay-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-developers-korapay-com-api-21a93a49/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### create_virtual_bank_account

Create a virtual bank account for a customer to receive payments via bank transfer.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `account_name` | string | Yes | Preferred account name |
| `account_reference` | string | Yes | Unique reference for the virtual account |
| `bank_code` | string | No | Bank code (e.g., 035 for Wema) |
| `customer_email` | string | Yes | Customer's email address |
| `customer_name` | string | Yes | Customer's name |
| `kyc_bvn` | string | No | Customer's BVN (required for some banks) |
| `permanent` | boolean | No | Whether the account is permanent or one-time |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-developers-korapay-com-api-21a93a49/create_virtual_bank_account \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_name":"<string>","account_reference":"<string>","bank_code":"<string>","customer_email":"<string>","customer_name":"<string>","kyc_bvn":"<string>","permanent":"<boolean>"}'
```

### create_virtual_card

Issue a new virtual card for a cardholder.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amount` | number | Yes | Initial funding amount |
| `brand` | string | No | Card brand (e.g., visa, mastercard) |
| `card_holder_reference` | string | Yes | The reference of the card holder |
| `currency` | string | No | Card currency |
| `reference` | string | Yes | Unique card creation reference |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-developers-korapay-com-api-21a93a49/create_virtual_card \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":"<number>","brand":"<string>","card_holder_reference":"<string>","currency":"<string>","reference":"<string>"}'
```

### get_all_pay_ins

Retrieve a history of all pay-in transactions.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `currency` | string | No | Filter by currency |
| `from` | string | No | Start date (YYYY-MM-DD) |
| `limit` | integer | No | Number of results per page |
| `page` | integer | No | Page number |
| `status` | string | No | Filter by status (e.g., success, failed) |
| `to` | string | No | End date (YYYY-MM-DD) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-developers-korapay-com-api-21a93a49/get_all_pay_ins \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency":"<string>","from":"<string>","limit":"<integer>","page":"<integer>","status":"<string>","to":"<string>"}'
```

### get_balances

Retrieve real-time available and pending balances for the authenticated account.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-developers-korapay-com-api-21a93a49/get_balances \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### initialize_checkout

Initialize a checkout/charge session to get a redirect URL for payment.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amount` | number | Yes | Amount to charge |
| `currency` | string | No | Currency code (e.g., NGN, GHS, KES) |
| `customer_email` | string | Yes | Customer's email address |
| `customer_name` | string | Yes | Customer's name |
| `narration` | string | No | Transaction description |
| `notification_url` | string | No | Webhook URL for payment notifications |
| `redirect_url` | string | Yes | URL to redirect the customer to after payment |
| `reference` | string | Yes | Unique transaction reference |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-developers-korapay-com-api-21a93a49/initialize_checkout \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":"<number>","currency":"<string>","customer_email":"<string>","customer_name":"<string>","narration":"<string>","notification_url":"<string>","redirect_url":"<string>","reference":"<string>"}'
```

### initiate_payout

Initiate a payout (disbursement) to a bank account or mobile money wallet.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `account_number` | string | No | Recipient bank account number (for bank_account) |
| `amount` | number | Yes | Amount to disburse |
| `bank_code` | string | No | Recipient bank code (for bank_account) |
| `currency` | string | No | Currency code |
| `customer_email` | string | No | Recipient email |
| `customer_name` | string | No | Recipient name |
| `destination_type` | string | No | Type of destination: bank_account or mobile_money |
| `mobile_number` | string | No | Recipient mobile number (for mobile_money) |
| `narration` | string | No | Transaction narration |
| `operator` | string | No | Mobile money operator slug (e.g., safaricom-ke) |
| `reference` | string | Yes | Unique disbursement reference |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-developers-korapay-com-api-21a93a49/initiate_payout \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_number":"<string>","amount":"<number>","bank_code":"<string>","currency":"<string>","customer_email":"<string>","customer_name":"<string>","destination_type":"<string>","mobile_number":"<string>","narration":"<string>","operator":"<string>","reference":"<string>"}'
```

### query_charge

Query the status and details of a charge transaction by reference.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `reference` | string | Yes | Transaction reference |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-developers-korapay-com-api-21a93a49/query_charge \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference":"<string>"}'
```

### query_payout

Retrieve the status and details of a payout transaction.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `reference` | string | Yes | Payout transaction reference |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-developers-korapay-com-api-21a93a49/query_payout \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference":"<string>"}'
```

### query_virtual_bank_account

Retrieve details of an existing virtual bank account.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `account_reference` | string | Yes | The unique reference of the virtual account |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-developers-korapay-com-api-21a93a49/query_virtual_bank_account \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_reference":"<string>"}'
```

### verify_bank_account

Verify a Nigerian bank account number and retrieve the account holder's name. Accepts a bank code and 10-digit account number, returns the resolved bank name, account number, and registered account holder name when the account is valid. Returns an upstream error when the account number is invalid or unresolvable.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `account_number` | string | Yes | 10-digit Nigerian bank account number to verify. |
| `bank_code` | string | Yes | Nigerian bank code identifying the bank where the account is held. |
| `currency` | string | No | Currency code for the bank account. Currently only NGN is supported. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-developers-korapay-com-api-21a93a49/verify_bank_account \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_number":"<string>","bank_code":"<string>","currency":"<string>"}'
```