{
"bvn": "22192474887",
"type": "Corporate",
"nin": "11111122221",
"virtual_account_type": "Permanent",
"account_name": "BOlaOla",
"rc_number": "99988828822",
"currency": "NGN",
"reference": "9ad98621-6763-491f-9a02-e0aa0d955318",
"customer_email": "hello@gmail.com"
}Our APIs are REST-based and designed to be intuitive and scalable. You can:
All requests must be authenticated and sent over HTTPS.
Ramp offers two distinct API environments: Sandbox (Test) and Live (Production). Understanding how each works ensures smooth integration and deployment.
🧪 Sandbox Environment
This environment is built for testing. It mimics real-world scenarios with simulated data — so you can build, test, and debug safely without affecting actual accounts or funds.
🚀 Live Environment
This is the production environment where real customers, data, and transactions are handled. Only move here after successful testing in the sandbox.
🔑 Key Things to Note:
✅ Get started by creating a free Ramp account or contacting support for access.
The Live environment is where real transactions take place and customer data is handled securely. Before moving to this environment, ensure your integration is thoroughly tested in the sandbox.
👍 Key Features
🔑 Key Points to Note
🌐 Live Environment URL
https://api.connectramp.com/api
🛠️ Steps to Get Started
🚧 Important Considerations
The Sandbox environment provides a secure and isolated space to test Ramp’s APIs. It replicates the live environment, allowing you to experiment without affecting real-world transactions.
In the Sandbox, you can:
These features are vital for validating your integration before moving to live operations.
Authentication secures your API requests through industry-standard encryption protocols and unique API keys. All requests must include valid authentication credentials transmitted securely over HTTPS to ensure that only authorized applications can access the payment processing functionality and sensitive data.
To access Ramp’s APIs, include the following header in each request:
<code></code>Authorization: Bearer <your-secret-key>You can find your secret and public keys on your developer dashboard.
An API endpoint (POST request to /api/virtual-accounts/create) that allows you to generate a new virtual account for a customer or business. It supports parameters such as bvn, nin, rc_number, account_name, and currency, along with specifying the type (e.g., Corporate) and virtual_account_type (e.g., Permanent). A unique reference and customer_email are also required for identification and communication purposes. This endpoint is ideal for enabling customers to receive payments directly into dedicated virtual accounts, streamlining collections and reconciliation processes.
{
"bvn": "22192474887",
"type": "Corporate",
"nin": "11111122221",
"virtual_account_type": "Permanent",
"account_name": "BOlaOla",
"rc_number": "99988828822",
"currency": "NGN",
"reference": "9ad98621-6763-491f-9a02-e0aa0d955318",
"customer_email": "hello@gmail.com"
}| Parameter | Description |
|---|---|
| bvn | Bank Verification Number of the customer or corporate entity. Example: “22192474887” |
| type | Type of account holder. Example: “Corporate” or “Individual”. |
| nin | National Identification Number of the account holder. Example: “11111122221” |
| virtual_account_type | Specifies whether the virtual account is “Permanent” or “Temporary”. |
| account_name | Name to be assigned to the virtual account. Example: “BOlaOla” |
| rc_number | Company registration number (for corporate accounts). Example: “99988828822” |
| currency | Currency for the virtual account. Example: “NGN” |
| reference | A unique identifier for the request, often a UUID. Example: “9ad98621-6763-491f-9a02-e0aa0d955318” |
| customer_email | Email address of the customer. Example: “hello@gmail.com” |
Card Processing enables secure handling of payment card transactions through our API, supporting various card types and verification methods. This service manages the entire lifecycle of card payments including validation, processing, settlement, and provides detailed transaction results for reconciliation purposes.
The GET Get Subaccounts endpoint retrieves a comprehensive list of all subaccounts associated with your primary account. This allows you to manage multiple business entities or payment destinations within a single integration, with each subaccount maintaining separate transaction histories and configurations.
The POST Initiate endpoint begins a new payment flow by creating a transaction session with specified parameters. This request establishes the foundation for subsequent payment operations, returning a unique identifier that can be referenced throughout the transaction lifecycle.
{
"reference": "{{$randomUUID}}",
"amount": "50",
"narration": "Narration heeeere",
"currency": "USD",
"card_data": {
"pan": "5399832641760090",
"cvv": "146",
"expiryMonth": "05",
"expiryYear": "50"
},
"callback_url": "https://redirect_url.com",
"metadata": {
"reason": "Payment for F1"
},
"device_information": {
"http_browser_language": "en-US",
"http_browser_java_enabled": false,
"http_browser_javascript_enabled": true,
"http_browser_color_depth": "24",
"http_browser_screen_height": "820",
"http_browser_screen_width": "360",
"http_browser_time_difference": "",
"user_agent_browser_value": "Mozilla/5.0 (Linux; Android 12; Infinix X6819) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Mobile Safari/537.36",
"device_channel": "Browser",
"ip_address": "54.144.139.131"
},
"billing_information": {
"postcodezip": "100001",
"street": "lagos",
"city": "lagos",
"country": "NGA",
"stateProvince": "lagos"
},
"customer_information": {
"email": "olu@gmail.com",
"firstName": "testFirstName",
"lastName": "testLastName",
"mobilePhone": "+1 555 1234 567"
},
"subaccount_id": "5d557a1c-66c2-47b2-9146-50f10af3cc4e"
}| Parameter | Description |
|---|---|
| Reference | A unique identifier for the transaction. It’s used to track or reference the payment later. Usually a UUID (e.g., {{$randomUUID}}). |
| Amount | The transaction amount to be charged. Example: “50”. |
| Narration | A short description of the transaction’s purpose (e.g., “Payment for services”). |
| Currency | The currency in which the payment is being made. Example: “USD”. |
| Card_Data | Contains the credit card information for the transaction. |
| pan | Card number (e.g., “5399832641760090”). |
| cvv | 3-digit security code on the card (e.g., “146”). |
| ExpiryMonth | 2-digit expiration month of the card (e.g., “05”). |
| ExpiryYear | 2-digit expiration year (e.g., “50” = 2050). |
| Callback_URL | The endpoint on your server to receive payment status updates after processing (e.g., “https://callbackurl.com”). |
| Metadata | Custom key-value pairs for internal use. Example: “reason”: “Payment for F1” |
| Device_Information | Used for fraud checks and 3DS authentication. |
| http_browser_language | Browser language (e.g., “en-US”). |
| http_browser_java_enabled | Whether Java is enabled (true/false). |
| http_browser_javascript_enabled | Whether JavaScript is enabled (true/false). |
| http_browser_color_depth: | Color depth of the user’s screen (e.g., “24”). |
| http_browser_screen_height | Screen height in pixels. |
| http_browser_screen_width | Screen width in pixels. |
| http_browser_time_difference | Timezone offset in minutes from UTC. |
| user_agent_browser_value | The full user agent string of the browser. |
| device_channel | Source of the transaction (e.g., “Browser”, “Mobile”). |
| ip_address | The user’s IP address. |
| billing_information | The billing address of the cardholder. |
| postcodeZip | ZIP or postal code. |
| Street | Street name or address. |
| City | City name. |
| Country | 3-letter ISO country code (e.g., “TUR” for Turkey). |
| stateProvince | State or province name. |
| customer_information | Basic details about the customer. |
| Customer’s email address. | |
| firstName | Customer’s first name. |
| lastName | Customer’s last name. |
| mobilePhone | Customer’s phone number in international format. |
| subaccount_id | The unique ID of the subaccount responsible for the transaction. This is obtained via the “Get Subaccount” API. |
The POST Charge endpoint processes payment transactions against customer payment methods, capturing funds for products or services. This essential endpoint supports multiple currencies, custom metadata, and provides detailed response data including authorization status and transaction identifiers.
{
"transaction_id": "SRK4NC92PFHLGZW78A3E"
}| Parameter | Description |
|---|---|
| transaction_id | A unique identifier for the transaction you want to charge. Example: “SRK4NC92PFHLGZW78A3E” |
The GET Query Transaction endpoint allows retrieval of detailed information about specific transactions using unique transaction identifiers. This functionality supports reconciliation processes, transaction monitoring, and provides visibility into payment statuses, amounts, and associated metadata.
An API endpoint (POST request to /momo/initiate) that allows you to initiate a mobile money (MoMo) transaction. This endpoint is designed to trigger a payment request to a user’s mobile wallet, using their phone number and preferred payment provider. It supports specifying transaction details such as amount, currency, and a unique customer reference. Useful for enabling seamless MoMo payments in applications targeting regions where mobile money is prevalent, ensuring secure and efficient transaction processing.
{
"customer_reference": "16401e05-0c12-4ccc-bbff-ee1a767d39f2",
"amount": "20",
"currency": "GHS",
"phone_no": "233801234567",
"payment_provider": "MTN"
}| Parameter | Description |
|---|---|
| pan | Mobile Money number or identifier (often the customer’s wallet number). Example: “4696660001638370” |
| subaccount_id | The ID of the subaccount initiating the transaction. Used to route or attribute the transaction correctly. Example: “9999999999”
|
| customer_reference | A unique identifier for the customer or transaction, often a UUID. Used to track or reconcile payments. Example: “16401e05-0c12-4ccc-bbff-ee1a767d39f2” |
| amount | The amount to be charged or paid. Example: “20” |
| currency | The currency of the transaction. Example: “GHS” |
| phone_no | The customer’s phone number in international format. Example: “233801234567” |
| payment_provider | The Mobile Money service provider to be used (e.g., “MTN”, “AIRTELTIGO”, “VODAFONE”). |
An API endpoint (POST request to /momo/process) that allows you to verify and complete a mobile money transaction by submitting a one-time password (OTP). This endpoint is typically used after initiating a MoMo transaction and receiving an OTP from the user, ensuring two-factor authentication and secure payment processing. It requires the unique transaction_id from the initiation phase and the user-provided otp to finalize the transaction. Ideal for workflows requiring user confirmation before funds are debited.
{
"transaction_id": "2JDSN4LBZWCRQEA9GXFH",
"otp": "200023"
}| Parameter | Description |
|---|---|
| transaction_id | The unique ID of the transaction being processed. Example: “2JDSN4LBZWCRQEA9GXFH” |
| otp | One-Time Password used to authorize the transaction. Example: “200023” |
| customer_reference | A unique identifier for the customer or transaction, often a UUID. Used to track or reconcile payments. Example: “16401e05-0c12-4ccc-bbff-ee1a767d39f2” |
| amount | The amount to be charged or paid. Example: “20” |
| currency | The currency of the transaction. Example: “GHS” |
| phone_no | The customer’s phone number in international format. Example: “233801234567” |
| payment_provider | The Mobile Money service provider to be used (e.g., “MTN”, “AIRTELTIGO”, “VODAFONE”). |
An API endpoint (GET request to /momo/requery/:customer_reference) that allows you to retrieve the status of a specific mobile money transaction using the customer_reference as a path parameter. This endpoint is useful for checking whether a transaction was successful, pending, or failed, enabling real-time status tracking and enhancing user transparency. Ideal for post-payment verification and automated reconciliation processes.
The general functionality that allows merchants to return funds to customers after a successful payment transaction. The refund system in JoinRamp includes both initiation and status checking capabilities.
An API endpoint (POST request to /v2/refund/initiate) that initiates a refund transaction. It requires the customer reference of the transaction as input in the request body and returns a status response indicating whether the refund was successfully initiated. This endpoint is essential for processing customer refunds programmatically.
{
"reference": "A74HULEKBXCRGQ2"
}| Parameter | Description |
|---|---|
| pan | The card number (Primary Account Number) used in the original transaction. Example: “4696660001638370” |
| subaccount_id | The ID of the subaccount initiating the refund. Example: “9999999999” |
| reference | A unique identifier for the initiated refund transaction. Example: “A74HULEKBXCRGQ2” |
An API endpoint (POST request to /v2/refund/initiate) that initiates a partial refund transaction. It requires the customer reference of the original transaction and the refund amount as input in the request body. The endpoint processes the refund and returns a status response indicating whether the partial refund was successfully initiated. This endpoint is essential for programmatically managing customer refund workflows, especially when only a portion of the original payment needs to be returned.
{
"reference": "A74HULEKBXCRGQ2"
"amount": "1.2"
}| Parameter | Description |
|---|---|
| pan | The card number (Primary Account Number) used in the original transaction. Example: “4696660001638370” |
| subaccount_id | The ID of the subaccount initiating the refund. Example: “9999999999” |
| reference | A unique identifier for the initiated refund transaction. Example: “A74HULEKBXCRGQ2” |
| amount | The amount to be refunded. Can be a partial or full value. Example: “1.2” |
An API endpoint (GET request to /v2/refund/query/:reference) that allows you to retrieve information about a specific refund using its reference ID as a path variable. This endpoint helps track the status and details of a previously initiated refund, enabling businesses to monitor refund processes and provide updates to customers.
A core feature that enables businesses to disburse funds to recipients, such as vendors, partners, or customers. The payouts system in JoinRamp supports seamless initiation of transfers and real-time tracking of payout statuses, ensuring transparency and timely settlements.
An API endpoint (GET request to /api/payout/banks) that allows you to retrieve a comprehensive list of supported banks. This endpoint is useful for populating bank options during user onboarding or when setting up payout and transfer operations, ensuring accuracy and reducing input errors.
| Parameter | Description |
|---|---|
| country_code (optional) | Used only for Mobile Money or Ghanaian account verification. Example: “GH” |
An API endpoint (POST /api/payout/accounts/validate) that allows you to validate a bank account number using the provided account number and bank code. It returns the corresponding account name, enabling you to confirm beneficiary details before processing payouts or transfers. This verification step helps prevent errors and ensures funds are sent to the correct recipient.
{
"account_number":"0112345678",
"bank_code":"999998"
// ,"country_code":"GH" use this for momo or gh related
}| Parameter | Description |
|---|---|
| account_number | The recipient’s bank or mobile money account number to verify. Example: “0112345678” |
| bank_code | The bank or mobile money provider code. Example: “058” for GTBank, “090267” for Kuda, “999998” for test, etc. |
| country_code (optional) | Used only for Mobile Money or Ghanaian account verification. Example: “GH” |
An API endpoint (POST /api/payout/disburse) used to initiate an interbank transfer from a merchant’s wallet to a beneficiary’s bank account. This request requires an api-key header for authorization and accepts a JSON payload containing the transfer amount, a unique customer reference, the destination bank code, account number, recipient name, and an optional narration. The endpoint facilitates seamless and secure disbursements while ensuring traceable transactions.
{
"customer_reference": "",
"account_number": "1234567890",
"bank_code": "000007",
"currency": "GHS",
"amount": "4",
"narration": "Testing",
"recipient_name": "John Doe",
"ref_id": "",
"sender_info": {
"name": "Test",
"phone": "090",
"email": "test@gmail.com"
}
}| Parameter | Description |
|---|---|
| customer_reference | A unique reference string for tracking the transaction. Should be unique per request. Example: “2772h727dycncwddfdfdfnnccffhrfjjhhf2dfdhfhhb7dfr3fddhdd2ery” |
| account_number | The beneficiary’s bank or wallet account number. Example: “0171605931” |
| bank_code | The code of the beneficiary’s bank or mobile money provider. Example: “058” for GTBank |
| amount | The amount to be transferred. Must be a numeric value as a string. Example: “120” |
| narration | A short description or reason for the transfer. Example: “Test Transfer” |
| recipient_name | Full name of the beneficiary. Example: “John DOE” |
| currency | The currency of the transaction. Example: “GHS” |
An API endpoint (GET /api/payout/requery/{transaction_id}) that retrieves the status of a specific transaction using its unique reference ID. This endpoint is useful for checking the outcome of a previously initiated disbursement, allowing businesses to confirm whether a transaction was successful, pending, or failed. It ensures transparency and supports troubleshooting or reconciliation processes.
Use these credentials for testing in the sandbox environment:
Only valid in the sandbox environment.
Use these cards for simulating card transactions:
| Card Number | Expiry | CVV | Response |
| 4242 4242 4242 4242 | 12/30 | 123 | Success |
| 4000 0000 0000 0002 | 12/30 | 123 | Failed |
Webhooks let you receive real-time updates from Ramp when events like payments or payouts occur. You must configure a webhook endpoint to start receiving data.
To set up a webhook for your business on Ramp:
✅ Once set, your system will begin receiving relevant webhook notifications based on your integrations.
Each webhook includes a signature header:
X-JR-Signature: <hash>To validate:
Triggered after a successful payment:
{
"event": "payment.success",
"data": {
"amount": 15000,
"currency": "NGN"
}
}Notifies you when a charge is completed:
{
"event": "charge.success",
"data": {
"method": "card",
"status": "completed"
}
}