# Cray Finance API Documentation — Full Content > Source: https://docs.crayfi.com This file concatenates every page of the Cray Finance documentation as plain Markdown so AI assistants can ingest the entire docs in one fetch. --- # Getting Started ## Overview URL: https://docs.crayfi.com/ Our Developer Documentation is here to walk you through all the steps of integrating powerful financial services right into your application. From your initial system set up (like authentication, setting up webhooks, and understanding the request structure) to actually creating financial products (like accounts, transfers, and cards), you can expect a detailed guide on going live with the Cray Finance API. We treat every business as a standalone organization, and that's why you need to sign up and create your Cray Finance account (or sign in if you already have one). You'll need to be signed into your Cray Finance Dashboard to manage and access critical resources like your organization's authentication keys, users, applications, customers, transactions, accounts, and everything else you do with the API. Cray Finance supports payment processing and collections in multiple African currencies, enabling cross-market operations and regional scalability. Currently, Cray processes payments in the following currencies: - Kenyan Shilling (KES) - Nigerian Naira (NGN) - Ghanaian Cedi (GHS) - South African Rand (ZAR) This multi-currency support allows businesses to build localized financial experiences while operating through a single, unified API. ## Build with the Cray API! The Cray API provides secure, reliable endpoints to power payments, collections, and financial workflows. Integrate quickly using clear REST APIs, predictable responses, and industry-standard authentication. ## What you can do - [Collections](/collections): Collect payments via Cards, Virtual accounts, Mobile Money and USDT - [Disbursements](/payouts): Initiate disbursements (payouts) and transfers - [Conversions](/conversions): Easily convert currencies and handle exchange rates in real time - [Refunds](/refunds): Quickly process full or partial refunds through the Refunds API. ## Built for developers Our API is designed with developers in mind. Clear documentation, predictable responses, and comprehensive error handling make integration straightforward. - [RESTful APIs with JSON responses](/cray-docs/status-codes): Easy to consume, consistent, and predictable data. - [Bearer token authentication](/cray-docs/authentication): Secure access with simple token-based authorization. - [Webhooks for real-time updates](/cray-docs/webhooks): Receive instant notifications on events and transactions. - [Sandbox and production environments](/cray-docs/environments): Test safely before going live! --- ## Using This Documentation URL: https://docs.crayfi.com/cray-docs/using-docs Learn how to make the best use of the Cray Finance API Docs ## Here's how we think you'd make the best use of these Docs: 1. Do not skip the overview pages of any section. It contains all the required fundamentals that you need to know about a product 2. When using the API playground tool, enter your Secret Key in the authentication header of any endpoint you want to try out, and you're good to go. 3. We suggest that you test our API endpoints with your own Postman application, as the API reference may not always contain all of the endpoints that we have. 4. If you do not understand any part of the Docs, please contact [Support](mailto:hello@crayfi.com) and ask any questions you may have. ![API Playground](/dev-server/src/assets/api-playground-2.png) --- ## Quick Start URL: https://docs.crayfi.com/cray-docs/quick-start You will see the request interface below. Follow these steps to send your first API request. ## 1. Visit our Endpoint Examples The endpoint examples tool is an interactive template set up to allow you to quickly simulate API calls to your CrayFinance account and immediately view the results, helping you understand how our endpoints work. ## 2. Authentication Most endpoints require secure access. To locate your API Key, follow these steps: On your cray finance dashboard, navigate to the settings page and scroll down to the **"API Keys"** section. Click on the "Create secret key" button to generate your API key. ## 3. Configure Your Request * **Method:** Select the HTTP method required for the endpoint (e.g., `GET` for retrieving data, `POST` for creating data) * **URL:** Enter the full endpoint URL (e.g., `https://pay.connectramp.com/api/get-subaccount`). ## 4. Adding Parameters If you are sending data to the API (like creating a new transaction), click the **Body** tab and enter your data in JSON format. For example ```json { "customer_reference": "e4d7c3b8-5f29-4b46-81a6-8d98c1e75812", "amount": "10", "currency": "NGN", "phone_no": "07020615945", "payment_provider": "opay", "otp": false, "return_url": "https://returnurl.com" } ``` ## 5. Custom Headers Click the **Send Request** button. The response will appear at the bottom of the tool: | Status Code | Error message | | --- | --- | | `OK (200)` | Success | | `Unauthorized (401)` | Invalid credentials supplied in header | | `Bad request (400)` | Check your JSON body formatting | **Response Body:** The data returned by the server, automatically formatted for readability Quick troubleshooting * System Error: IF the request fails immediately, ensure you are not blocked by a firewall or VPN. * JSON Error: Ensure your keys and string values are wrapped in double quotes `""`. Single quotes `''` are not valid in JSON. --- ## The Cray Finance Dashboard URL: https://docs.crayfi.com/cray-docs/dashboard Learn how the Dashboard supports your integration needs ![The Cray Finance Dashboard](/dev-server/src/assets/Cray-Dashboard.avif) The Cray Finance Dashboard gives you all the tools and insights you need to integrate, monitor, and manage everything happening on your application through the Cray Finance API. As you'll see throughout this documentation, the Dashboard provides powerful back-office functionality across all our products — including creating accounts, viewing transaction details, freezing or unfreezing accounts, and more. Everything available on the Dashboard can also be performed directly via the API. Below are a few important things to note: ### Balances Your Cray finance dashboard is the central place for tracking all inflows and outflows across your organisation. You'll find your balances clearly displayed here. Cray Finance provides two types of balances on the Dashboard: * Main Balance * Settlement Balance Currently, Cray Finance supports multiple currencies, including **NGN, USD, and KES**, for both balances ### Main Balance Your **Main Balance** is the primary wallet on the Cray Finance Dashboard. It works just like a business account for your organisation within Cray Finance. All fees, commissions, transfers, and similar transactions are debited from this balance. Withdrawals from the Main Balance can only be done using the Transfers feature on the Dashboard. ### Settlement Balance The **Settlement Balance** is a temporary holding balance. This is where all payments received through Checkout and Collection Accounts are settled. When you receive funds through these channels, the money is added to your Settlement Balance. **The next working day**, Cray Finance collates the total amount received and pays it out either to your designated settlement bank account or your Main Balance. **Can I withdraw from my Settlement Balance?** No. The Settlement Balance cannot be withdrawn from directly because it is a temporary balance. To access the funds, you must wait until the next working day for the payout into either your bank account or your Main Balance. ### KYB Verification ![Cray KYB](/dev-server/src/assets/Cray-KYB.avif) Every organisation onboarded to Cray Finance is required to complete KYB verification. This process ensures compliance with regulatory standards and helps us maintain a secure and trusted financial ecosystem. During KYB verification, you will not be able to go live. However, you can still explore and test the Cray Finance API in **Test Mode**. --- ## Setting up 2FA URL: https://docs.crayfi.com/cray-docs/setting-up-2fa Enable two-factor authentication to secure your Cray Finance account and protect sensitive operations. Two-factor authentication (2FA) adds an extra layer of security to your Cray Finance account. Once enabled, you'll need to provide a time-based verification code alongside your password when performing sensitive actions. We strongly recommend enabling 2FA immediately after creating your account. It protects against unauthorized access and is required for high-risk operations like payouts and IP whitelisting. ## Getting Started Upon login, merchants who have not yet enabled 2FA will see a **prompt banner** on their dashboard encouraging them to set it up. Clicking the call-to-action button redirects you to the **Security** tab within the **Settings** page. ## Step-by-Step Setup ### Step 1: Navigate to Security Settings Go to **Settings → Security** in your Cray Finance dashboard and click **Enable 2FA**. ### Step 2: Scan the QR Code Once you click Enable 2FA, the system automatically generates: - A **QR code** for scanning with an authenticator app (e.g. Google Authenticator, Authy) - A **secure setup key/URL** that can be manually entered into the authenticator app if scanning is not possible Open your preferred authenticator app and scan the QR code, or tap "Enter setup key" and paste the provided key manually. ### Step 3: Enter the Verification Code After scanning the QR code or entering the setup key, your authenticator app will generate a **time-based verification code** (OTP). Enter this 6-digit code in the portal to verify your setup. ### Step 4: Save Your Recovery Key Once verified, 2FA is successfully enabled. A **secret recovery key** will be generated — store this key securely. You will need it to regain access to your account if you lose your authenticator device. Your recovery key is shown only once. Save it in a secure location such as a password manager. Cray Finance cannot recover this key for you. ## Actions That Require 2FA With 2FA activated, additional verification is required for sensitive actions within the portal. You must provide your OTP when performing any of the following operations: - **Whitelisting a new IP address** - **Adding a new user or sub-account** - **Initiating bulk or single payouts** - **Creating payment links** Each OTP is valid for a short window (typically 30 seconds). If your code expires, simply wait for a new one to be generated by your authenticator app. --- ## Environments URL: https://docs.crayfi.com/cray-docs/environments Learn how to build on staging and production with Cray Finance Cray 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. 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 simulate different card payment scenarios to ensure your integration handles them correctly. These features are vital for validating your integration before moving to live operations. ## 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** **Separation**: Sandbox and Live environments are fully isolated — with different API keys, business IDs, and credentials **Real vs Simulated Data:** Sandbox transactions are simulated. Live transactions involve actual money and customer data. **Environment URLs:** - **Staging**: `https://dev-gateman.v3.connectramp.com/` - **Live:** `https://pay.connectramp.com` --- ## Authentication URL: https://docs.crayfi.com/cray-docs/authentication Learn how to authenticate your connection to the Cray Finance API To interact with the Cray Finance API, you must first authenticate your requests. We use API keys to identify and authorize every call you make. Without a valid API key, your requests will fail. 🚧 **Important:** Requests with a missing, invalid, or incorrect API key will fail with a `401 Unauthorised` error. ## Finding Your API Keys To find your API keys, sign in to your Cray Finance Dashboard. Go to **Settings → Developer**. You will see two types of keys: a **Public Key** and a **Secret Key**. ## Understanding Your API Keys ### 1. Public Key (`lrp_...`) Your Public Key is your organization's identifier. It is safe to use in your client-side code (like your website or mobile app). Its primary use is to initialize our client-side widgets and identify your account when creating tokens. Public keys cannot modify your account or access sensitive data. ### 2. Secret Key (`lrs_...`) Your Secret Key is highly confidential and must never be shared publicly (e.g., in front-end code, public repositories, or insecure messages). This key is used for all server-side API calls and grants full access to your account, including accessing data, moving funds, and modifying settings. Treat your Secret Key like a password. Always store your secret keys securely and consider rotating them periodically. 📘 **Tip** You can revoke and generate new API keys at any time from the Developer settings page. If you suspect a key has been compromised, generate a new one immediately and update your integration. ## Authenticating Your API Call To authenticate a server-side request, include your Secret Key in the `Authorization` header using the `Bearer` scheme. ``` Authorization: Bearer lrs_xxxxxxxxxxxxxxxxx ``` 📘 **Note** When adding this to your code, replace `lrs_xxxxxxxxxxxxxxxxx` with your actual Secret Key. Remember to use your **Test Key** for development and your **Live Key** for production. ## Troubleshooting 401 Errors If you are consistently receiving `401 Unauthorised` error responses, check for these common issues: * **Using an old or revoked key:** When you generate a new API key, any previous key is automatically revoked. Ensure all your services are updated with the new key. * **Using the wrong key type:** You cannot use a Public Key (`lrp_...`) for server-side authentication. Server-side requests always require a Secret Key (`lrs_...`). * **Typo in the key:** API keys are long, complex strings. It's best to copy and paste your key directly from the dashboard. Do not type it manually. * **Wrong environment:** Your Test Mode keys are different from your Live Mode keys. They are not interchangeable. Confirm you are using the correct key for the environment you are targeting. --- ## IP Whitelisting URL: https://docs.crayfi.com/cray-docs/ip-whitelisting Restrict API access to trusted IP addresses for enhanced security IP Whitelisting allows you to restrict API access to only specific, trusted IP addresses. This adds an extra layer of security by ensuring that requests to the Cray Finance API can only originate from your known servers or infrastructure. ## How It Works When IP Whitelisting is enabled, Cray Finance will reject any API request that does not originate from one of your whitelisted IP addresses, regardless of whether a valid API key is provided. ## Setting Up IP Whitelisting Log in to your Cray Finance Dashboard and go to **Settings → Security**. Enter the IP addresses you want to whitelist. You can add multiple IPs to cover all your server environments. Click **Save** to activate IP Whitelisting. All subsequent API requests must originate from the listed IPs. **Important:** Make sure to include all server IPs that need API access before enabling this feature. Failing to do so will block legitimate requests. If you use dynamic IPs or cloud infrastructure with changing addresses, consider using a static IP or a proxy to ensure consistent access. --- ## Test Credentials URL: https://docs.crayfi.com/cray-docs/test-credentials Use test credentials to simulate transactions in the staging environment Cray Finance provides test credentials that allow you to simulate transactions in the staging environment without using real money or real customer data. ## Test API Keys Your test API key is available on your Cray Finance Dashboard under **Settings → API Keys**. Test keys are prefixed with `lrp_` to distinguish them from live keys. Test keys only work in the **Staging** environment. They cannot be used to process real transactions. ## Test Card Details Use the following test card details to simulate payment scenarios: | Field | Value | | --- | --- | | PAN | `4084080000000409` | | CVV | `000` | | Expiry Month | `11` | | Expiry Year | `26` | Test cards can **only** be used in the **staging environment**. They will not work in production. Always test your full integration flow in the staging environment before switching to live credentials. This ensures all edge cases are handled properly. --- ## Webhooks URL: https://docs.crayfi.com/cray-docs/webhooks Learn how to use webhooks to receive real-time notifications from Cray Finance. Webhooks are automated messages sent from Cray Finance to your application. They are the most reliable way to receive real-time updates when events happen in your account, such as a successful payment, a new customer, or a completed payout. Instead of your application constantly asking our API if an event has occurred (known as “polling”), our system will instantly send a notification (a POST request) to your server when the event happens. To start receiving these notifications, you must register a secure URL (a webhook endpoint) on your server. ## How to Set Up Your Webhook Follow these steps to tell Cray Finance where to send your event notifications: - Log in to your Cray Finance Dashboard. - Navigate to the Your Business section from the main navigation menu. - Click on the Webhook tab. - On this page, find the Webhook Configuration section. - Enable Webhooks: Check the box labeled "Enable Webhooks." This activates the feature. - Enter Your Endpoint URL: In the "URL" field, paste the secure URL from your application that is built to listen for incoming webhook data. **Important:** For security, this URL must be an HTTPS endpoint (it must start with https://). HTTP URLs will not be accepted. - Save Your Configuration: Click the "Set Webhook" or "Save" button. - Once saved, Cray Finance will immediately begin sending live event data to this URL whenever a relevant event occurs in your account. ## Webhook Security: Verifying Signatures To ensure that the webhook events you receive are truly sent by our system and have not been tampered with, we sign every webhook request using a Hash-based Message Authentication Code (HMAC). We strongly recommend that you verify this signature before processing any webhook event. ### The Signature Header Every webhook request will include a custom HTTP header containing the signature: `X-Webhook-Signature` ### How the Signature is Generated We generate the signature using the following formula: ```php Signature = base64_encode( hash_hmac('sha256', , , true) ) ``` - **Algorithm:** HMAC-SHA256 - **Key:** Your unique Webhook Secret Key (provided in your dashboard). - **Payload:** The raw JSON body of the request. - **Encoding:** The binary hash output is encoded in Base64. ## Verifying the Signature (Step-by-Step) To verify the webhook, your server should follow these steps: 1. **Retrieve the Header:** Extract the signature string from the X-Webhook-Signature header. 2. **Get the Raw Body:** Read the raw request body bytes. Do not parse the JSON into an object yet; you must use the exact raw string bytes as they were sent. 3. **Compute the Hash:** Use your Secret Key and the Raw Body to compute the HMAC-SHA256 hash. 4. **Encode:** Convert the computed hash to a Base64 string. 5. **Compare:** Compare your computed signature with the signature in the header. Use a constant-time string comparison function to prevent timing attacks. ### Code Examples #### 1. PHP ```php { req.rawBody = buf; }, }) ); app.post("/webhook", (req, res) => { const signature = req.headers["x-webhook-signature"]; // Create the hash const expectedSignature = crypto .createHmac("sha256", SECRET) .update(req.rawBody) .digest("base64"); // Constant-time comparison if ( crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expectedSignature) ) ) { // Verified! console.log("Webhook verified"); res.status(200).send("Received"); } else { res.status(403).send("Invalid Signature"); } }); ``` ## Cray Finance Webhook Events ### Collection Success Webhook This event is triggered immediately after a successful payment or fund collection has been processed and credited to your Cray Finance account. ```json { "event": "payment.success", "data": { "amount": 15000, "currency": "NGN", "reference": "CRF_TXN_0012345" // Added common field for better context } } ``` ### Charge Status Webhook This event notifies you when a customer interaction, such as a checkout or a direct card charge, is completed, regardless of the final status. ```json { "event": "charge.success", "data": { "method": "card", "status": "completed", "transaction_id": "CRF_CHG_987654" // Added common field for better context } } ``` ## Retrieving Failed Webhook Events Webhooks that could not be successfully delivered after the standard retry period are logged as failed events. It's critical to regularly check this list to ensure you don't miss important financial notifications. This endpoint is your primary tool for monitoring and troubleshooting webhook delivery issues. ### Endpoint: Get All Permanently Failed Webhooks | Method | URL | Description | | --- | --- | --- | | `GET` | /api/payout/failedWebhook | Retrieves a list of all webhook delivery attempts that have permanently failed. | #### Example Request You must include your Secret Key in the Authorization header to access this endpoint. ```bash curl -X GET 'https://pay.connectramp.com/payout/failedWebhook' \ -H 'Authorization: Bearer sk_live_your_secret_key' ``` #### Example Response The response returns an array of objects, where each object represents a single failed webhook delivery attempt. ```json { "success": true, "data": { "success": true, "data": [ { "id": 50, "created_at": "2025-10-01T08:44:45.399Z", "updated_at": "2025-10-01T08:44:45.399Z", "url": "https://v01zqdg3-7148.euw.devtunnels.ms/v-1/payment/callback", "user_id": "127", "data": { "data": { "amount": "1.00", "charge": "300.00", "merchant_reference": "97_uztmeh_qi628a", "processor_reference": "999999250930072041448704496616", "recipient_account_number": "898789", "recipient_bank_code": "78978", "recipient_name": null, "reference": "48LWAY7FE5RTNGD1759213240", "status": "Successful" }, "event": "transaction_complete", "hash": "pEdGMWXpneeROpaML/L7w6UPTLfciP4SCsbYaAJBAHg=" }, "headers": { "Content-Type": "application/json", "x-api-key": "bHJwX1ZHbU51TVFjY1pzT2J3Vkt6NDFRc3pwenlncEJHdkZKO2xyc193bHRsdWI1eVZpM1NGWEhtMzBrWE1IVXgzMUVFVVVyVA==" } }, { "id": 51, "created_at": "2025-10-02T00:06:25.225Z", "updated_at": "2025-10-02T00:06:25.225Z", "url": "https://v01zqdg3-7148.euw.devtunnels.ms/v-1/payment/callback", "user_id": "127", "data": { "data": { "amount": "1600.00", "charge": "300.00", "failure_reason": "Transaction rejected by authorizer", "merchant_reference": "58_eubzqp_vjmprx", "processor_reference": null, "recipient_account_number": "898789", "recipient_bank_code": "78978", "recipient_name": null, "reference": "76F38215SRTXENH1759359170", "status": "Failed" }, "event": "transaction_complete", "hash": "KqeuzxTTts/DfLOW2kFfIRIi+jquDHLzEcDmGcBW01M=" }, "headers": { "Content-Type": "application/json", "x-api-key": "bHJwX1ZHbU51TVFjY1pzT2J3Vkt6NDFRc3pwenlncEJHdkZKO2xyc193bHRsdWI1eVZpM1NGWEhtMzBrWE1IVXgzMUVFVVVyVA==" } }, { "id": 52, "created_at": "2025-10-02T00:11:45.405Z", "updated_at": "2025-10-02T00:11:45.405Z", "url": "https://v01zqdg3-7148.euw.devtunnels.ms/v-1/payment/callback", "user_id": "127", "data": { "data": { "amount": "1600.00", "charge": "300.00", "failure_reason": "failed", "merchant_reference": "19_kuoiil_mr26pn", "processor_reference": "e586837d-5c0a-416b-a4ee-9c1d34badb3b", "recipient_account_number": "898789", "recipient_bank_code": "78978", "recipient_name": null, "reference": "PBA4V7G9HEU8DT21759359172", "status": "Failed" }, "event": "transaction_complete", "hash": "mD08+mr2H9zdmIG+8P/fumw+rtH/kk8kVmODSwdwWog=" }, "headers": { "Content-Type": "application/json", "x-api-key": "bHJwX1ZHbU51TVFjY1pzT2J3Vkt6NDFRc3pwenlncEJHdkZKO2xyc193bHRsdWI1eVZpM1NGWEhtMzBrWE1IVXgzMUVFVVVyVA==" } } ], "message": "Failed webhook retrieved" }, "message": "Action was Succesfull" } ``` **Retry Failed Webhook:** If a webhook delivery fails (e.g., your server was down or returned a non-200 status code), Cray Finance will retry the delivery automatically for a period. If all retries are exhausted, the event will remain in the failed log. You can use this endpoint to manually reprocess a specific failed webhook notification after you have resolved the issue with your endpoint (network errors, server downtime, etc.). ### Retry a Specific Failed Webhook | Method | URL | | --- | --- | | `GET` | /api/payout/failedWebhook/{webhookId} | To retry the delivery of the failed webhook with the ID 50: ```bash curl -X GET 'https://pay.connectramp.com/api/payout/failedWebhook/50' \ -H 'Authorization: Bearer sk_live_your_secret_key' ``` #### Example Response: Successful Retry A successful response indicates that the system has accepted the request and is attempting to redeliver the webhook payload to your endpoint. ```json { "success": true, "message": "Webhook retry initiated" } ``` --- ## Status Codes URL: https://docs.crayfi.com/cray-docs/status-codes Cray Finance categorizes transaction outcomes into distinct statuses ### CLR001 – Security Violation This transaction was flagged and declined due to exceeding the allowed number of transactions within a specific time frame (velocity limit) for the card. This is a preventive measure against potential misuse or automated fraudulent activity. ### CLR002 – Security Violation This transaction failed an internal fraud detection mechanism. It may have been identified as suspicious due to unusual patterns such as high-risk geolocation, blacklisted accounts, or anomalies in behavior based on historical data. ### CLR003 – Single Transaction Limit Exceeded The transaction amount exceeded the maximum allowed limit for a single transaction, as defined by cardholder or account policy. To proceed, the transaction must be split or limits adjusted. ### Pending — Initiated Charge The transaction has been initiated and is awaiting further processing. It may be awaiting a user action (e.g., OTP or 3D Secure authentication). ### Successful The transaction was processed and authorized without any issues. ### Failed The transaction could not be completed due to an error. This may be due to insufficient funds, declined authorization, or system-level interruptions. ### Abandoned The user initiated the transaction but did not complete the required steps. This typically happens when users close the app/browser, get redirected without finalizing payment, or fail to respond to authentication prompts. ### PMN-96-422 – System Malfunction The transaction failed due to an internal system malfunction on the payment network or processing platform. Please retry the transaction later or contact support if the issue persists. ### PMN-59-422 – Suspected Fraud The transaction was declined because it was flagged as potentially fraudulent based on risk or security checks. To proceed, verify the transaction details or follow additional authentication and fraud-prevention procedures. ### E03 – Insufficient Balance (Default) The transaction could not be completed due to insufficient wallet balance. To proceed, ensure the sender has adequate funds. ### E04 – System Error (ETP) The transaction failed due to a temporary system error on the payment processing platform. Please retry the transaction later. ### E05 – Insufficient Balance The sender's wallet balance is insufficient to process the transaction. To proceed, top up the wallet and retry. ### E06 – Insufficient Balance or Limit Reached The transaction failed because the sender's wallet balance is insufficient or a transaction limit has been reached. To proceed, ensure sufficient balance and verify applicable limits. ### E08 – Transaction Limit Exceeded The transaction amount exceeds the allowed wallet, daily, or per-transaction limit. To proceed, reduce the amount or adjust the applicable limits. ### E01 – Invalid PIN Length The transaction failed because the provided PIN does not meet the required length. To proceed, ensure the PIN matches the configured minimum and maximum length. ### E02 – Insufficient Balance The sender's wallet does not have enough funds to complete the transaction. To proceed, fund the wallet and retry. ### E07 – Internal Processing Error The transaction could not be completed due to an internal processing error. Please retry the transaction or contact support if the issue persists. ### E09 – Invalid Sender MSISDN The sender's mobile number (MSISDN) is invalid or improperly formatted. To proceed, provide a valid and correctly formatted MSISDN. ### E10 – Invalid OTP The one-time password (OTP) provided is incorrect or has expired. To proceed, request a new OTP and retry. ### E11 – Payment Request Failed The payment request could not be initiated or completed successfully. Please retry the request or contact support if the issue persists. ### E12 – Sender Account Not Active The sender's mobile money account is inactive, suspended, or not registered. To proceed, activate the account before retrying. ### E13 – Invalid Payee MSISDN The recipient's mobile number (MSISDN) is invalid or improperly formatted. To proceed, provide a valid recipient MSISDN. ### E14 – Transaction Timeout During Approval The transaction timed out while awaiting user or system approval. Please retry the transaction. ### E15 – Transaction Timeout The transaction could not be completed due to a timeout. Please retry the transaction later. ### E16 – Wrong PIN The transaction failed because an incorrect PIN was provided. To proceed, enter the correct PIN. ### 200 – Success Standard success response for conversion initialization, completion, listing, setting and fetching rates, and when a quote is generated. ### 401 – Unauthorized When a user cannot be identified for a dispute request. ### 403 – Forbidden The FX_CONVERSION feature is not available for the user. ### 404 – Not Found - Quote ID is invalid or expired. - Transaction (credit or debit) not found during completion. - Conversion not found during dispute creation. - Merchant not found when setting custom rates. - Rate not found (general, merchant-specific, or by ID). ### 409 – Conflict An open dispute already exists for the conversion reference. ### 412 – Precondition Failed - Unable to fetch source or destination wallet. - Insufficient balance in the source wallet. ### 422 – Unprocessable Entity - Invalid quote payload (amount or rate Understanding these statuses helps in monitoring transaction outcomes and implementing appropriate business logic. --- ## SDKs URL: https://docs.crayfi.com/cray-docs/sdks Explore our SDKs designed to simplify integration across multiple programming languages and frameworks. Whether you're building a mobile app, a web application, or integrating with a popular e-commerce platform, we've got SDKs tailored to your specific needs. Each solution is designed to streamline the integration process, allowing you to focus on building great products while leveraging our powerful payments infrastructure. Our SDKs are designed to simplify the integration of our payment APIs across multiple programming languages and development frameworks. With our SDKs, developers can access various features such as Cards, Mobile money, Foreign exchange and more. Each SDK is equipped with comprehensive documentation to guide you through the installation, authentication, and usage process, making the integration experience smooth and efficient. ## Supported SDKs --- ## Libraries URL: https://docs.crayfi.com/cray-docs/libraries Explore available libraries for integrating with Cray Finance. Whether you're working with a specific framework or platform, our libraries provide pre-built integrations that accelerate your development workflow. Each library is tailored to the conventions and patterns of its respective ecosystem, so you can get up and running with minimal configuration. Our libraries wrap the core Cray APIs into framework-native packages, giving you access to payment processing, wallet management, and more — all through familiar interfaces and idioms. They handle authentication, request formatting, and error handling out of the box, letting you focus on building your application logic. ## Available Libraries --- ## Cray Woocommerce Payment Plugin URL: https://docs.crayfi.com/cray-docs/plugins E-commerce plugins for integrating Cray payments into your online store. The official **Cray Payments** plugin for WooCommerce allows you to accept payments on your WordPress store using Cray's secure payment infrastructure. [Download WooCommerce Plugin (.zip)](/downloads/cray-woocommerce-gateway-v1.1.3.zip) ## Features * **Card Payments** — Accept Visa, Mastercard, and Verve cards securely. * **Mobile Money (MoMo)** — Support for mobile money payments across multiple African countries (Nigeria, Ghana, Kenya, etc.). * **3D Secure** — Full support for 3D Secure (3DS) authentication to prevent fraud. * **Webhooks** — Automatic order status updates via webhooks. * **Subaccounts** — Support for splitting payments to subaccounts. * **Secure** — Sensitive card data is never stored on your server. ## Installation & Setup ### Step 1: Install the Plugin 1. Download the plugin zip file. 2. Log in to your WordPress Admin Dashboard. 3. Go to **Plugins** > **Add New**. 4. Click **Upload Plugin** at the top. 5. Choose the zip file you downloaded and click **Install Now**. 6. After installation, click **Activate**. ### Step 2: Enable the Payment Gateway 1. Go to **WooCommerce** > **Settings**. 2. Click on the **Payments** tab. 3. Find **Cray Payments** and toggle the switch to **Enable**. 4. Click **Manage** (or "Set up") next to Cray Payments to configure your settings. ### Step 3: Configure API Keys You need your API keys from your Cray Dashboard. 1. **Environment** — Select `Sandbox` for testing or `Live` for real payments. 2. **Public Key** — Enter your Cray Public Key. 3. **Secret Key** — Enter your Cray Secret Key. 4. **Default Currency** — Select the currency you want to process payments in (e.g., USD, NGN). 5. Click **Save Changes**. ### Step 4: Configure Webhooks > **info:** Webhooks allow Cray to notify your store when a payment is successful, ensuring orders are updated even if the user closes their browser. 1. In the plugin settings page, look for the **Webhook Endpoint** field. 2. Copy the URL (e.g., `https://yourstore.com/wp-json/cray/v1/webhook`). 3. Log in to your **Cray Dashboard**. 4. Navigate to **Settings** > **Webhooks**. 5. Paste the URL and save. ## Payment Methods You can choose which payment methods to display on checkout by going to the main Cray settings page (usually under a "Cray Payments" submenu or the main plugin settings). * **Card Only** — Show only the credit/debit card form. * **MoMo Only** — Show only the Mobile Money option. * **Both** — Allow customers to choose between Card and MoMo. ## Testing (Sandbox Mode) 1. Ensure **Environment** is set to `Sandbox` in the plugin settings. 2. Use the test cards provided in the Cray documentation to simulate successful and failed transactions. 3. Check the **WooCommerce > Status > Logs** (select `cray-woocommerce-gateway` from the dropdown) to debug any issues. ## Frequently Asked Questions **Q: Where can I find my API Keys?** Log in to your Cray Dashboard and navigate to the Developer/API Settings section. **Q: My orders are not updating to "Processing" after payment.** Ensure you have configured the **Webhook URL** correctly in your Cray Dashboard (see Step 4). **Q: Is this plugin secure?** Yes. Card details are tokenized and processed securely by Cray. We do not store sensitive card information (PAN, CVV) on your server. ## Support If you encounter any issues, please check the logs in **WooCommerce > Status > Logs** or contact Cray support. --- # Wallet ## Cray wallets URL: https://docs.crayfi.com/wallet Learn about Cray wallets and multi-currency wallet management Cray Wallets are digital accounts that allow your application to track and display balances in multiple African currencies. Currently, Cray supports the following currencies: * Kenyan Shilling (KES) * Nigerian Naira (NGN) * Ghanaian Cedi (GHS) * Zambian Kwacha (ZMW) * West African CFA Franc (XOF) ### Key points about Cray Wallets 1. **Balance Display Only** * Wallets reflect the available balance in each supported currency. * They do **not automatically convert** between currencies; each wallet balance is tied to a specific currency. 2. **Multi-Currency Support** * You can create separate wallets for different currencies if your users or organization operate across multiple regions. * The API returns balances in the currency associated with each wallet. 3. **Read & Track Balances via API** * Use the Cray Wallets API to retrieve balances. * Wallets provide a clear, real-time view of funds available per currency. 4. **Integration with Cray Products** * Wallets can be linked to transfers, payouts, and cards. * They act as a single point of reference for all your multi-currency financial operations within Cray. | Method | URL | Description | | ------ | --- | ----------- | | GET | /api/balance | Get wallet balance | **Request parameter:** | Parameter | Description | Value | | --------- | ----------- | ----- | | Currency | Filter accounts by currency code | NGN, USD, GHS | **Example request:** ```bash curl --location -g 'https://pay.connectramp.com/api/balance?currency=NGN' \ --header 'Authorization: Bearer ' ``` **Example response:** ```json { "status": "success", "message": "Account balance retrieved successfully", "data": { "accounts": [ { "id": "account-uuid-1", "account_name": "Main Account", "currency": "NGN", "account_type": "SAVINGS", "account_number": "1234567890", "available_balance": 50000.00, "locked_balance": 5000.00, "actual_balance": 55000.00 }, { "id": "account-uuid-2", "account_name": "USD Account", "currency": "USD", "account_type": "CURRENT", "account_number": "0987654321", "available_balance": 1000.00, "locked_balance": 0.00, "actual_balance": 1000.00 } ] } } ``` ```json { "status": "success", "message": "No accounts found", "data": [] } ``` ```json { "status": false, "message": "Unable to fetch account balance at this time, please try again", "error": [] } ``` --- ## Get Wallet Balance URL: https://docs.crayfi.com/wallet/get-balance Method: `GET` Endpoint: `GET https://pay.connectramp.com/api/balance` Track and display Cray wallet balances in multiple currencies --- # Collections ## Collections overview URL: https://docs.crayfi.com/collections Cray Finance Collections provide a suite of tools to help your business accept and reconcile payments efficiently. Whether you are receiving funds via bank transfers, card payments, or mobile wallets, the Collections API enables you to automate the entire process, reduce manual effort, and maintain accurate financial records. Through our multi-channel approach, you can: * Accept payments from a wide variety of sources * Automate reconciliation for faster processing * Provide a seamless experience for your customers Cray Collections currently include three main services: **Virtual Accounts, Card Processing, and Mobile Money**. ## 1. Virtual Accounts Cray Finance Virtual Accounts let you generate **dedicated account numbers** for your customers or transactions, streamlining both collections and reconciliation. **Benefits:** * **Easy Customer Payments** – Customers pay directly to a unique account number without extra steps. * **Automated Reconciliation** – Each account is tied to a customer or invoice, allowing instant matching of incoming payments. * **Flexible Account Types** – Create **Permanent Accounts** for ongoing use or **Temporary Accounts** for one-time collections. ## 2. Card Processing Cray Card Processing allows you to **handle all payment card transactions securely** through the API, supporting multiple card types and standard verification methods. **Benefits:** * **End-to-End Card Management** – From validation and authorization to processing and settlement. * **Detailed Transaction Data** – Access transaction results and use webhooks for real-time updates. * **Simplified Reconciliation** – Transaction metadata allows for automated matching and reporting. ## 3. Mobile Money Mobile Money (MoMo) enables payments directly from **mobile wallets**, making it ideal for Africa and other emerging markets. **Benefits:** * **Wide User Reach** – Tap into mobile wallet users who prefer cashless mobile payments. Cray Mobile Money integration is available in KES, NGN, GHS, ZMW, XOF * **Secure & Convenient** – Transactions are fast, reliable, and integrated into your app. * **Seamless Integration** – Collect payments seamlessly through the API. --- ## Virtual accounts URL: https://docs.crayfi.com/collections/virtual-accounts Cray Finance Virtual Accounts offer dedicated accounts for easy collection and reconciliation. Cray Finance Virtual Accounts provide a powerful tool for streamlining your collections and reconciliation process. By generating a dedicated virtual account number for each customer or transaction, you can enable them to receive payments directly via bank transfer. This allows for: * **Easy Customer Payments:** Customers simply transfer funds to a unique account number. * **Automated Reconciliation:** Since each account is tied to a specific entity or reference, your system can instantly and accurately link the incoming payment to the correct customer or invoice, eliminating manual tracking. We support the creation of both **Permanent** (tied to a customer for continuous use) and **Temporary** (for one-time or specific collections) virtual accounts. ### Create virtual account: | Method | URL | Description | |--------|-----|-------------| | POST | /api/virtual-accounts/create | Generates one or more virtual account numbers associated with the provided customer details. | **Request body payload:** | Parameter | Description | Example | |-----------|-------------|---------| | BVN | Bank Verification Number of the customer or corporate entity. | "22192474887" | | Type | Type of account holder. Must be Corporate or Individual. | "Corporate" | | NIN | National Identification Number of the account holder (often required for individuals). | "11111122221" | | virtual_account_type | Specifies the account purpose: Permanent (long-term customer account) or Temporary (for a single transaction). | "Permanent" | | account_name | The desired name to be assigned to the virtual account. | "BOlaOla" | | rc_number | Company registration number (required for Corporate accounts). | "99988828822" | | currency | The currency for the virtual account. Currently supports NGN. | "NGN" | | reference | A unique identifier you generate for this specific creation request (e.g., a UUID or internal customer ID). | "9ad98621-6763-491f-9a02-e0aa0d955318" | | customer_email | The email address of the customer for identification and communication. | "hello@gmail.com" | **Example request:** ```bash curl --location -g 'https://pay.connectramp.com/api/virtual-accounts/create' \ --header 'Authorization: Bearer ' \ --data-raw '{ "bvn": "22192474887", "type": "Corporate", "nin": "11111122221", "virtual_account_type": "Permanent", "account_name": "BOlaOla", "rc_number": "99988828822", "currency": "NGN", "reference": "cbf0d060-1544-4a53-a00b-7cb75a3eb59d", "customer_email": "hello@gmail.com" }' ``` **Example response:** ```json { "success": true, "message": "Action was Successful", "data": [ { "bankCode": "035", "bankName": "Wema bank", "accountNumber": "4114669663", "accountName": "BOl" }, { "bankCode": "232", "bankName": "Sterling bank", "accountNumber": "2242249783", "accountName": "BOl" } ] } ``` ### Submit OTP to Complete Virtual Account Creation (Wema Bank Only) After successfully creating a virtual account, an **OTP (One-Time Password)** is sent to the customer's registered email address. This OTP must be submitted to verify the account creation and activate the virtual wallet. | Method | URL | Description | |--------|-----|-------------| | POST | /api/virtual-accounts/generate-wallet | Generates one or more virtual account numbers associated with the provided customer details. | **Request body payload:** | Parameter | Description | |-----------|-------------| | otp | The one-time password sent to the customer's email. | | customer_email | The email address associated with the virtual account. | **Example request:** ```bash curl --location -g 'https://pay.connectramp.com/api/virtual-accounts/generate-wallet' \ --header 'Authorization: Bearer ' \ --data-raw '{ "otp": "768238", "customer_email": "hello@gmail.com" }' ``` **Example response:** ```json { "success": true, "message": "Action was Successful" } ``` ### Get Subaccounts | Method | URL | Description | |--------|-----|-------------| | GET | /api/get-subaccount | Fetches the full list of your configured subaccounts. | **Example request:** ```bash curl --location -g 'https://pay.connectramp.com/api/get-subaccount' \ --header 'Authorization: Bearer sk_live_your_secret_key' ``` **Example response:** ```json { "status": true, "message": "SubAccount Details", "data": [ { "uuid": "9999999999", "company_name": "test", "company_email": "test@gmail.com" } ] } ``` --- ## Card collections URL: https://docs.crayfi.com/collections/card-collections Card Processing enables the secure handling of all payment card transactions through the Cray Finance API, supporting various card types and industry-standard verification methods. This service manages the entire lifecycle of card payments, from initial validation and authorization to final processing and settlement. It provides you with detailed transaction results and webhooks, which are essential for timely and accurate reconciliation purposes. ### Initiate card payment The **Initiate** endpoint begins a new payment flow by securely creating a transaction session with all specified parameters (card details, amount, customer info, etc.). This request establishes the foundation for subsequent payment operations, returning a unique identifier that must be referenced throughout the transaction lifecycle. | Method | URL | |--------|-----| | POST | /api/v2/initiate | **Request Body Payload:** | Parameter | Description | |-----------|-------------| | reference | A unique identifier for the transaction. It's used to track or reference the payment later. Usually a UUID. | | 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. | | metadata | Custom key-value pairs for internal use. Example: "reason": "Payment for F1" | | 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. | | email | 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. | **Example request:** ```bash curl --location 'https://pay.connectramp.com/api/v2/initiate' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "reference": "4aeb118e-5009-450a-94fc-d74f6cd88646", "amount": "1", "narration": "Narration here", "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": "test@testmail.com", "firstName": "testFirstName", "lastName": "testLastName", "mobilePhone": "+1 555 1234 567" }, "subaccount_id": "b0e1a8c2-5d9f-4f3b-9d72-6a3e2f8e5c14" }' ``` **Example response:** ```json { "status": true, "message": "Transaction Initialized", "data": { "status": "AUTHENTICATION_INITIATED", "transaction_id": "X27TKSDUPL8VNRHJ9Z3Y" } } ``` ### Process Payment: Charge Endpoint The **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. | Method | URL | |--------|-----| | POST | /api/v2/charge | **Request Body Payload:** | Parameter | Description | |-----------|-------------| | transaction_id | A unique identifier for the transaction you want to charge. Example: "SRK4NC92PFHLGZW78A3E" | **Example request:** ```bash curl --location 'https://pay.connectramp.com/api/v2/charge' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "transaction_id": "SRK4NC92PFHLGZW78A3E" }' ``` **Example response:** ```json { "status": true, "message": "Charge attempted", "data": { "status": "redirect_auth", "reference": "921ba7dc-b080-4da9-886e-a18920fa7b2f", "redirect_auth_data": { "customizedHtml": { "3ds2": { "acsUrl": "https://acsv2.m2pfintech.com/emv/auth/process/10058/creq", "cReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImU1ZjVmY2YxLTk5YmMtNDZmYy1hNTkzLTExMjM2ODAwNGFmOCIsImFjc1RyYW5zSUQiOiIyNWQ3MGU5OC05OGQ2LTQzOTAtODhlYi1hNTFlMThhZjk0OWQiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIn0" } }, "domainName": "acsv2.m2pfintech.com", "html": " var e=document.getElementById(\"threedsChallengeRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } " } } } ``` ```json { "status": true, "message": "Charge attempted", "data": { "status": "redirect_auth", "reference": "286ba835-6ec4-4545-b008-0338881b741c", "redirect_auth_data": "https://dev-gateman.v3.connectramp.com/api/load-threedes?modal_url=https%3A%2F%2Fstandard.paystack.co%2Fcharge%2Fauth%2Fd2d50f49neovqb5cce2%3Flang%3Den&redirect_url=https%3A%2F%2Fdev-gateman.v3.connectramp.com%2Fapi%2Fvalidate-3ds%2F286ba835-6ec4-4545-b008-0338881b741c" } } ``` ### Query transaction The **Query Transaction** endpoint lets you pull up all the detailed info about any transaction using its unique ID. This is your go-to tool for easily checking payment statuses, amounts, and everything you need for quick reconciliation and monitoring. | Method | URL | |--------|-----| | GET | /api/query/:reference | **Example request:** ```bash curl --location 'https://pay.connectramp.com/api/query/{reference}' \ --header 'Authorization: Bearer ' ``` **Example response:** ```json { "status": true, "message": "Charge attempted", "data": { "status": "Successful", "reference": "87c89286-afbc-4776-adfd-665c9927b2db", "provider_reference": "F6L2RN8TM7AHZ491SCGQ", "amount": 5, "net_amount": 4.73, "fee": 0.28, "payment_channel": "card", "redirect_url": "https://redirect_url.com", "callback_url": "https://redirect_url.com", "customer": { "name": "Deion Haag", "email": "user@joinramp.co" }, "metadata": "", "retrieval_reference_number": "774848", "stan": "999595958", "created": "2025-03-21T07:47:03.000000Z" } } ``` --- ## Mobile money URL: https://docs.crayfi.com/collections/mobile-money Mobile Money (MoMo) is a game-changer for payments, especially in Africa and other emerging markets! This service lets your users make payments directly from their mobile phone wallets, offering a secure, widespread, and incredibly convenient alternative to traditional banking. Integrating MoMo through Cray Finance means you can seamlessly tap into this massive user base, enabling quick and reliable transactions that feel native to their mobile experience. It’s the simple way to expand your reach and make collecting payments effortlessly accessible. ### Initiate Mobile Money (MoMo) Transaction The **Initiate** endpoint is how you kick off a Mobile Money (MoMo) payment! This endpoint is designed to immediately trigger a payment request to a user's mobile wallet, using their phone number and preferred payment provider. It lets you specify all the transaction details like the amount, currency, and a unique customer reference. It's super useful for enabling seamless and efficient MoMo payments in applications targeting regions where mobile money is super prevalent. | Method | URL | | ------ | ---------------------------------------------------------------------------------------------------- | | GET | /api/v2/momo/initiate | **Request body payload:** | Parameter | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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", "XOF", "NGN", "KES" | | 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", "MPESA", "Opay"). | **Example request:** ```bash curl --location 'https://pay.connectramp.com/api/v2/momo/initiate' \ --header 'Authorization: Bearer ' \ --data '{ "customer_reference": "e4d7c3b8-5f29-4b46-81a6-8d98c1e75812", "amount": "10", "currency": "NGN", "phone_no": "07020615945", "payment_provider": "opay", "otp": false, "return_url": "https://returnurl.com" }' ``` **Example response:** ```json { "status": true, "message": "Transaction is processing", "data": { "status": "Processing", "reference": "TNW4UKB1XQZSVP86E7AR", "customer_reference": "b6f4268e-2e20-4167-af84-a13f46f8344a", "amount": "3950.00", "currency": "NGN", "phone_no": "+2348146152814", "provider_message": null, "payment_provider": "Opay", "redirect_url": null, "date": "2025-11-24T14:42:19.000000Z" } } ``` ### Query transaction The **Query** endpoint is your quick check-in to see exactly what happened with a Mobile Money transaction! It allows you to instantly retrieve the final status of a specific payment by using the unique `customer_reference` from the very start of the process. This is super useful for checking whether a transaction was successful, pending, or failed, giving you and your users real-time visibility. It's the ideal tool for post-payment verification and making sure your reconciliation processes are perfectly automated! | Method | URL | | ------ | --------------------------------------------------------------------------------------------------------------------------------- | | GET | /api/v2/requery/{customer_reference} | **Example request:** ```bash curl --location 'https://pay.connectramp.com/momo/requery/{customer_reference}' \ --header 'Authorization: Bearer ' ``` **Example response:** ```json { "status": true, "message": "Transaction confirmation status", "data": { "status": "Failed", "reference": "2JDSN4LBZWCRQEA9GXFH", "customer_reference": "ad75b9bb-2501-4761-8980-42b525e21c37", "amount": "20.00", "currency": "GHS", "phone_no": "233801234567", "payment_provider": "MTN", "date": "2025-07-30T09:31:29.000000Z" } } ``` --- ## Stable Coins URL: https://docs.crayfi.com/collections/stable-coins Cray Finance supports cryptocurrency collections via stable coins, starting with USDT on the TRON network. Stable coin collections provide a fast, borderless payment method for your customers with near-instant settlement and minimal fees. Cray Finance enables businesses to accept payments in **USDT (Tether)** — a widely adopted stable coin pegged to the US Dollar. This provides your customers with a fast, borderless, and low-fee payment option. ## Supported Stable Coins | Stable Coin | Network | Status | |-------------|---------|--------| | **USDT** | TRON (TRC-20) | ✅ Available | More stable coins and blockchain networks will be added in the future. Currently, **USDT on TRON** is the only supported option. ## How It Works The stable coin collection flow is simple and developer-friendly: Call `GET /api/virtual-accounts/crypto/supported-assets` to get valid asset codes. Never hardcode them. Call `POST /api/accounts/crypto/vault` with a unique name and `assetId`. This provisions a virtual wallet and returns a deposit address for your customer. Share the returned deposit address with your customer. They send the exact USDT amount to that TRON address. ## Key Features - **Fixed USD Value**: USDT is pegged 1:1 to the US Dollar, eliminating volatility risk - **Fast Settlement**: TRON network transactions typically confirm within seconds - **Low Fees**: Minimal network fees compared to traditional payment rails - **Payment URL**: Each transaction generates a hosted payment page for easy customer experience - **Expiry Window**: Payment sessions have a configurable expiry window (default ~2 hours) Ensure your customers send the **exact amount** of USDT specified in the transaction. Underpayments or overpayments may require manual reconciliation. ## Integration To start collecting USDT payments, use the endpoints below. All requests should be sent to: ```bash https://pay.connectramp.com/api ``` Supported endpoints: - `GET /api/virtual-accounts/crypto/supported-assets` - `POST /api/accounts/crypto/vault` ## Get Supported Assets Before creating a vault, you must retrieve the list of crypto assets available on the platform. This endpoint returns all supported assets along with their identifiers, names, network details, and symbols. Each asset is tied to a specific blockchain network. For example, USDT on the TRON network will have a unique `assetId` that you must use when creating a vault. Always fetch the supported assets dynamically rather than hardcoding `assetId` values, as the available assets may change. **Endpoint:** `GET /api/virtual-accounts/crypto/supported-assets` **Auth:** `Authorization: Bearer {{token}}` **Request body:** None **cURL:** ```bash curl --location 'https://pay.connectramp.com/api/virtual-accounts/crypto/supported-assets' \ --header 'Authorization: Bearer {{token}}' ``` ## Create Vault/Asset A vault is a virtual wallet provisioned for a specific crypto asset. Once created, it generates a unique deposit address that you share with your customer so they can send funds directly to it. To create a vault, call this endpoint with a unique name and the `assetId` returned from the Get Supported Assets endpoint. The API provisions the wallet on the specified blockchain and returns the deposit address, QR code, and other metadata. **Endpoint:** `POST /api/accounts/crypto/vault` **Auth:** `Authorization: Bearer {{token}}` **Body:** ```json { "name": "Avengers09909", "assetId": "TRX_USDT_S2UZ" } ``` **cURL:** ```bash curl --location 'https://pay.connectramp.com/api/accounts/crypto/vault' \ --header 'Authorization: Bearer {{token}}' \ --data '{ "name": "Avengers09909", "assetId": "TRX_USDT_S2UZ" }' ``` Use a unique name per vault. The `assetId` must match a value returned from the Get Supported Assets endpoint. --- ## Create Virtual Account URL: https://docs.crayfi.com/collections/create-virtual-account Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/virtual-accounts/create` Use this endpoint to generate a new, unique virtual bank account number for a customer or business entity --- ## Create A One-Time Virtual Account URL: https://docs.crayfi.com/collections/create-onetime-virtual-account Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/virtual-accounts/create` Use this endpoint to create a one-time virtual account for a single collection. The account expires after the first successful payment. --- ## Submit OTP URL: https://docs.crayfi.com/collections/submit-otp Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/virtual-accounts/generate-wallet` After successfully creating a virtual account, an OTP (One-Time Password) is sent to the customer’s registered email address. This OTP must be submitted to verify the account creation and activate the virtual wallet. (Wema Bank Only) --- ## Get Subaccounts URL: https://docs.crayfi.com/collections/get-subaccounts Method: `GET` Endpoint: `GET https://pay.connectramp.com/api/get-subaccount` List of all subaccounts currently associated with your primary Cray Finance account. --- ## Initiate Card Transaction URL: https://docs.crayfi.com/collections/initiate-card Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/v2/initiate` The Initiate endpoint begins a new payment flow by securely creating a transaction session with all specified parameters (card details, amount, customer info, etc.). This request establishes the foundation for subsequent payment operations, returning a unique identifier that must be referenced throughout the transaction lifecycle. --- ## Process Payment URL: https://docs.crayfi.com/collections/process-payment Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/v2/charge` The 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. --- ## Query Transaction URL: https://docs.crayfi.com/collections/query-transaction Method: `GET` Endpoint: `GET https://pay.connectramp.com/api/query/{customer_reference}` The Query Transaction endpoint lets you pull up all the detailed info about any transaction using its unique ID. This is your go-to tool for easily checking payment statuses, amounts, and everything you need for quick reconciliation and monitoring --- ## Initiate URL: https://docs.crayfi.com/collections/initiate-mobile-money Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/v2/momo/initiate` Trigger a payment request to a user’s mobile wallet --- ## Requery URL: https://docs.crayfi.com/collections/requery-mobile-money Method: `GET` Endpoint: `GET https://pay.connectramp.com/api/v2/momo/requery/{customer_reference}` Your quick check-in to see exactly what happened with a Mobile Money transaction --- ## Get Supported Assets URL: https://docs.crayfi.com/collections/get-supported-assets Method: `GET` Endpoint: `GET https://pay.connectramp.com/api/virtual-accounts/crypto/supported-assets` Fetch the list of supported crypto assets. Each asset returns an assetId tied to a specific blockchain network. Always call this first — never hardcode asset IDs. --- ## Create Vault/Asset URL: https://docs.crayfi.com/collections/create-vault Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/accounts/crypto/vault` Create a crypto vault for your customer. Provide a unique name and a valid assetId from the Get Supported Assets endpoint. Returns a deposit address the customer can send funds to. --- # Payouts ## Payouts URL: https://docs.crayfi.com/payouts This guide provides a developer-focused walkthrough of the Cray Finance Payouts API. Integrating our payout functionality involves a series of API calls designed to ensure accuracy, security, and a smooth user experience. Following this workflow will help you build a robust payout system. ### Supported Payout Currencies Our platform supports payouts in the following currencies: * **USD**: United States Dollar * **ZMW**: Zambian Kwacha * **GHS**: Ghanaian Cedi * **XOF**: West African CFA franc * **NGN**: Nigerian Naira ### Payout Process Overview The payout workflow is designed to be sequential and idempotent. Each step provides necessary information for the next, culminating in the final disbursement. The core process is as follows: 1. **Fetch Available Payment Methods**: Dynamically determine which payout channels are available for a given country. 2. **Fetch Supported Banks**: Retrieve an up-to-date list of supported banks for bank transfer operations. 3. **Validate Beneficiary Account**: Perform a pre-transaction check to verify account details and receive a reference ID. 4. **Initiate Disbursement**: Execute the payout transaction using the reference ID to send funds to the recipient. 5. **Requery Transaction Status**: Asynchronously check the final status of the payout. --- ### 1. Fetch Available Payment Methods **Endpoint**: `GET /payout/payment-methods/{countryCode}` Before initiating a payout, your application needs to know which payment channels (e.g., bank transfer, mobile money) are supported in the target country. By calling this endpoint with a country code, you receive a list of valid payment methods. #### URL Parameters * `countryCode` (string, required): The two-letter ISO 3166-1 alpha-2 country code (e.g., `NG` for Nigeria). --- ### 2. Fetch Supported Banks **Endpoint**: `GET /payout/banks` For bank transfer payouts, it's crucial to provide users with an accurate list of supported institutions. This endpoint returns a comprehensive list of all banks integrated with our system. It requires no parameters. --- ### 3. Validate Beneficiary Account **Endpoint**: `POST /payout/accounts/validate` To prevent failed transactions, validate the beneficiary's account details before attempting a disbursement. By submitting the user's account number and bank code, the API returns the registered account name and a unique reference ID (`ref_id`) for the validation session. **This ID is required to process the transaction in the next step.** #### Request Body * `account_number` (string, required): The beneficiary's bank account number. * `bank_code` (string, required): The unique code for the beneficiary's bank, retrieved from the `GET /payout/banks` endpoint. #### Example Payload ```json { "account_number": "0112345678", "bank_code": "058" } ``` The response will contain a `ref_id` in the data object, which you must pass to the disbursement endpoint. --- ### 4. Initiate Disbursement **Endpoint**: `POST /payout/disburse` Once the account is validated, you can initiate the payout. This endpoint processes the actual fund transfer to the recipient's account. The `ref_id` from the validation step must be included in the request to link the disbursement to a verified account. #### Example Payload * `customer_reference` (string, required): A unique identifier for the transaction from your system. * `amount` (number, required): The amount to be disbursed. * `narration` (string, required): A brief description of the transaction. * `ref_id` (string, required): The reference ID obtained from the account validation step. This links the disbursement to a successful validation. The exact structure of the payload will vary depending on the payout currency. The example below is for a disbursement in **XOF**. You can test the endpoint on the process transfer page listed on the sidebar menu to see other currencies' payload. ```json { "amount": 5000, "currency": "XOF", "account_number": "770000000", "customer_reference": "PDN-PAYOUT-001", "narration": "Payout", "receipient_info": { "account_number": "770000000", "bank_code": "orange-money-senegal" } } ``` --- ### 5. Requery Transaction Status **Endpoint**: `GET /payout/requery/{transaction_id}` Payouts are often processed asynchronously. After initiating a disbursement, use this endpoint to determine its final status. #### URL Parameters * `transaction_id` (string, required): The unique transaction ID returned by the `POST /payout/disburse` endpoint. --- ## Cross-currency Payouts URL: https://docs.crayfi.com/payouts/cross-currency-payouts Send money in one currency while the recipient receives it in another — with automatic conversion at the applicable exchange rate. Cross-currency payouts allow businesses to send money in one currency while the recipient receives it in another currency. The platform automatically performs the currency conversion using the applicable exchange rate before completing the payout. This feature is useful for cross-border payments, where the sender operates in a different currency from the recipient. For example, a business can send funds in USD or EUR, while the recipient receives the payout in XOF in their mobile money wallet or local account. The conversion happens automatically during the payout process, ensuring that the recipient receives the equivalent amount in their local supported currency. Cross-currency payouts help simplify international disbursements by removing the need for manual currency conversions. --- ## Bulk Payouts URL: https://docs.crayfi.com/payouts/bulk-payouts Send multiple payouts to different recipients in a single API request for efficient, high-volume disbursements. Bulk payouts allow businesses to send multiple payouts to different recipients in a single API request. Instead of creating separate payout requests for each recipient, bulk payouts enable you to submit a batch of payout instructions at once, improving efficiency and reducing the number of API calls required. This feature is commonly used for payroll disbursements, marketplace seller payouts, affiliate commissions, vendor payments, and mass refunds. By processing multiple transactions in a single request, businesses can streamline payment operations and handle large-scale disbursements more effectively. Each payout in the batch contains its own recipient details, amount, and reference, while the platform processes the entire list as part of a single bulk payout operation. This approach simplifies reconciliation and makes it easier to manage high-volume payment workflows. --- ## Single-currency Payouts URL: https://docs.crayfi.com/payouts/single-currency-payouts Send and receive funds in the same currency — no conversion needed, ideal for domestic payments. Single currency payouts allow businesses to send and receive funds in the same currency. In this type of payout, the currency used by the sender is the same currency the recipient receives, meaning no currency conversion is required during the transaction. This payout method is typically used for domestic payments within supported countries, where both the sender and recipient operate in the same currency. For example, a business can send funds in XOF, and the recipient receives the payout in XOF through their mobile money wallet or local account. Single currency payouts are commonly used for local vendor payments, agent settlements, merchant withdrawals, and other domestic disbursements, providing a simple and efficient way to transfer funds without involving exchange rates or cross-border conversions. --- ## Stable Coin Payouts URL: https://docs.crayfi.com/payouts/stable-coin-payouts Send USDT and other supported stablecoins to any compatible on-chain wallet via a simple three-step workflow. Stable coin payouts let you disburse funds in stablecoins (e.g., USDT on Tron or Solana) directly to your customers' or partners' on-chain wallets. The flow is intentionally sequential: you first discover which assets are supported, then register the destination wallet as a beneficiary, and finally initiate the actual on-chain payout. This guide walks through each of the three endpoints involved, what they do, the headers and body each one expects, and example requests and responses you can copy into your integration. ## Get Supported Assets `GET /api/virtual-accounts/crypto/supported-assets` This is always the first call in the stable coin payout flow. It returns the full list of assets your account is authorized to send, along with the blockchain, network protocol, and the canonical `id` you must use when adding beneficiaries or initiating payouts. You should never hardcode asset identifiers in your application. Networks evolve, new assets are added, and existing ones can be deprecated. By calling this endpoint dynamically you ensure that the `asset`/`currency` field you submit downstream always matches a value the platform currently supports. Each asset object also exposes useful metadata such as `decimals` (used to format amounts correctly in your UI), `networkProtocol` (so you can surface the correct chain to your user, e.g. TRX vs SOL), and `testnet` (so you can clearly separate staging from production assets). ### Headers | Header | Value | | --- | --- | | `Authorization` | `Bearer {{token}}` | ### Example Request ```bash curl --location 'https://pay.connectramp.com/api/virtual-accounts/crypto/supported-assets' \ --header 'Authorization: Bearer {{token}}' ``` ### Example Response ```json { "status": true, "message": "Supported assets retrieved successfully", "data": { "data": [ { "algorithm": "MPC_ECDSA_SECP256K1", "baseAsset": "TRX", "blockchain": "TRX", "blockchainSymbol": null, "coinType": 195, "decimals": 6, "deprecated": false, "ethContractAddress": null, "hasFee": true, "id": "TRX_USDT_S2UZ", "issuerAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "name": "USD Tether (Tron)", "networkProtocol": "TRX", "symbol": "USDT", "testnet": false, "type": "TRON_TRC20" }, { "algorithm": "MPC_EDDSA_ED25519", "baseAsset": "SOL", "blockchain": "SOL", "blockchainSymbol": null, "coinType": 501, "decimals": 6, "deprecated": false, "ethContractAddress": null, "hasFee": true, "id": "SOL_USDT_EWAY", "issuerAddress": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB", "name": "USDT (Solana)", "networkProtocol": "SOL", "symbol": "USDT", "testnet": false, "type": "SOL_ASSET" } ] } } ``` ## Add Beneficiary `POST /api/payout/crypto/beneficiaries` Once you know which assets are supported, the next step is to register the recipient's on-chain wallet as a beneficiary. A beneficiary is a saved (`name`, `asset`, `wallet_address`) tuple that the platform uses to validate the destination, prevent address typos from causing irreversible losses, and link future payouts to a known recipient for reporting. The `asset` field must be exactly one of the `id` values returned by **Get Supported Assets** — it determines which blockchain the `wallet_address` will be validated against. Submitting a Solana address with a Tron `asset` (or vice versa) will be rejected. Crypto transactions are irreversible. Always confirm the `wallet_address` and `asset` match the recipient's intended network before adding a beneficiary. ### Headers | Header | Value | | --- | --- | | `Authorization` | `Bearer {{token}}` | | `Content-Type` | `application/json` | ### Body ```json { "name": "OMU", "asset": "TRX_USDT_S2UZ", "wallet_address": "t21qererlxcfu24davl2r5sqmgzzgsal6wusda40er" } ``` ### Example Request ```bash curl --location 'https://pay.connectramp.com/api/payout/crypto/beneficiaries' \ --header 'Authorization: Bearer {{token}}' \ --header 'Content-Type: application/json' \ --data '{ "name": "OMU", "asset": "BTC_TEST", "wallet_address": "tb1qerzrlxcfu24davlur5sqmgzzgsal6wusda40er" }' ``` ## Initiate Payout `POST /api/payout/crypto/initiate-payout` This is the call that actually moves funds on-chain. It debits your stablecoin balance and broadcasts a transfer to the wallet identified by `address_reference`. Field reference: - `amount` — the amount to send, denominated in the asset's units (e.g. `"2"` USDT). - `currency` — the asset `id` from **Get Supported Assets** (e.g. `TRX_USDT_S2UZ`). It must match the asset of the beneficiary you're sending to. - `address_reference` — the unique identifier of the saved beneficiary returned when you added them via **Add Beneficiary**. - `customer_reference` — your own unique reference for this payout. Use it for idempotency and to reconcile the transaction in your system. - `narration` — a short, human-readable description of the payout, useful for internal reporting. The response returns a Cray `reference` you should persist; this is the canonical ID you'll use to track status updates, requery the transaction, or correlate webhook events. Always generate a unique `customer_reference` per payout. Reusing references can cause duplicate detection to reject otherwise valid transactions. ### Headers | Header | Value | | --- | --- | | `Authorization` | `Bearer {{token}}` | | `Content-Type` | `application/json` | ### Body ```json { "amount": "2", "currency": "TRX_USDT_S2UZ", "address_reference": "f3f47d77-acf9-4e97-8d85-4b05fe6487cd", "customer_reference": "d751b9ad2cf79hhh9000", "narration": "testPayouhht" } ``` ### Example Request ```bash curl --location 'https://pay.connectramp.com/api/payout/crypto/initiate-payout' \ --header 'Authorization: Bearer {{token}}' \ --header 'Content-Type: application/json' \ --data '{ "amount": "50", "currency": "TRX_USDT_S2UZ", "address_reference": "eaaa2950-ddfd-43a8-a4d5-bbde9b8aa8be", "customer_reference": "d751b9ad2cf799000", "narration": "testPayout" }' ``` ### Example Response ```json { "success": true, "data": { "reference": "BK7QVUN5LRX6YE11777892030", "amount": "50", "charge": 0, "status": "Pending", "recipient_name": "ZINOL", "recipient_bank_code": null, "recipient_account_number": "tb1qerzrlxcfu24davlur5sqmgzzgsal6wusda40er", "processor_reference": null, "merchant_reference": "d751b9ad2cf799000" }, "message": "Crypto payout initiated" } ``` --- ## Get Payment Methods URL: https://docs.crayfi.com/payouts/get-payment-methods Method: `GET` Endpoint: `GET https://pay.connectramp.com/api/payout/payment-methods/{countryCode}` The GET Payment Methods endpoint is your handy way to instantly see all available payout options for a specific country! You just use the in the path, and it tells you exactly which payment methods—like bank transfer, mobile money, or wallet options—are supported in that region. This is super useful for dynamically showing only valid payout channels and making sure your users can select the correct options during disbursement setup! --- ## Get Banks URL: https://docs.crayfi.com/payouts/get-banks Method: `GET` Endpoint: `GET https://pay.connectramp.com/api/payout/banks` The GET Banks endpoint is your one-stop shop to easily grab a comprehensive list of all supported banks! This is super useful for making your app smooth for users. You can use it to instantly populate bank options during user onboarding or when they’re setting up payout and transfer operations, which helps ensure total accuracy and cuts down on frustrating input errors! --- ## Account Name Lookup URL: https://docs.crayfi.com/payouts/account-name-lookup Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/payout/accounts/validate` The Validate endpoint is your handy tool for making sure money goes to the right person! It allows you to validate a bank account number instantly using just the provided account number and bank code. It quickly returns the corresponding account name, which is super helpful for you to confirm the beneficiary’s details before processing any payouts or transfers. This quick verification step totally prevents errors and ensures your funds are always sent to the correct recipient! --- ## Process Transfer URL: https://docs.crayfi.com/payouts/process-transfer Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/payout/disburse` The POST Disburse endpoint is what you use to easily send money from your merchant wallet right into a beneficiary’s bank account! This request is super important for seamless and secure disbursements to your vendors, partners, or customers. It requires your API key for authorization and accepts a simple JSON payload containing the transfer amount, a unique customer reference, the destination bank code, account number, recipient name, and an optional narration. It ensures all your transfers are traceable and processed quickly! --- ## Verify Transaction URL: https://docs.crayfi.com/payouts/verify-transaction Method: `GET` Endpoint: `GET https://pay.connectramp.com/api/payout/requery/{transaction_id}` The GET Requery endpoint is your instant way to check on any money you’ve sent out! It allows you to immediately retrieve the current status of a specific payout using its unique transaction_id as a path parameter. This is super useful for confirming whether a disbursement was successful, pending, or failed, which ensures transparency and makes troubleshooting or reconciliation processes a total breeze! --- ## Get Supported Assets URL: https://docs.crayfi.com/payouts/get-supported-assets Method: `GET` Endpoint: `GET https://pay.connectramp.com/api/virtual-accounts/crypto/supported-assets` Retrieve the full list of stablecoins your account can send. Always call this first to get the canonical assetId you'll use when adding beneficiaries and initiating payouts. --- ## Add Beneficiary URL: https://docs.crayfi.com/payouts/add-crypto-beneficiary Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/payout/crypto/beneficiaries` Register a recipient's on-chain wallet as a beneficiary. The asset must be a valid id from the Get Supported Assets endpoint and determines which blockchain the wallet_address is validated against. --- ## Initiate Payout URL: https://docs.crayfi.com/payouts/initiate-crypto-payout Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/payout/crypto/initiate-payout` Move funds on-chain to a saved beneficiary. The currency must match the beneficiary's asset, and customer_reference should be unique per payout to ensure idempotency. --- # Conversions ## How Conversions Work URL: https://docs.crayfi.com/conversions This guide provides a step-by-step overview of the currency conversion process, from checking exchange rates to disputing a transaction. ## Supported Currencies - **USD**: United States Dollar - **ZMW**: Zambian Kwacha - **GHS**: Ghanaian Cedi - **XOF**: West African CFA franc - **NGN**: Nigerian Naira ## 1. Get Exchange Rates Before initiating a conversion, you can check the current exchange rates. ### A. Get a Specific Exchange Rate POST /merchant/rates Retrieves the exchange rate, Service Level Agreement (SLA), and settlement type for a specific currency pair. ```json { "success": true, "data": [ { "id": 4, "source_currency": "EUR", "destination_currency": "NGN", "rate": "5002.000000", "sla": 0, "settlement": "automatic", "status": "Active" }, { "id": 19, "source_currency": "USD", "destination_currency": "NGN", "rate": "1450.000000", "sla": 3, "settlement": "automatic", "status": "active" } ] } ``` ### B. Get Rates by Destination Currency POST /merchant/rates/destination Retrieves all available exchange rates for a given destination currency. ## 2. Generate a Quote POST /merchant/quote Before converting, you must generate a quote. The quote locks in the conversion rate for a specific duration (default: 10 minutes). **Request:** ```json { "destination_currency": "USD", "source_currency": "NGN", "source_amount": 1500 } ``` **Response:** ```json { "success": true, "data": { "quote_id": "quote:f9d96be7-5653-4e90-a5ad-4420db7b0195", "conversion_rate": 1600, "expires_in_minutes": 10 }, "message": "Quote generated" } ``` ## 3. Execute Conversion POST /merchant/conversions/convert Finalizes the conversion using a valid `quote_id` obtained from the "Generate a Quote" endpoint. **Request:** ```json { "quote_id": "quote:98a5d6d3-7cbc-4c7d-b4f6-d3bbbbe340b6" } ``` **Response:** ```json { "success": true, "data": { "quote_id": "quote:98a5d6d3-7cbc-4c7d-b4f6-d3bbbbe340b6", "debit_transaction_id": 2605, "credit_transaction_id": 2606, "settlement": "automatic", "sla_minutes": 0 }, "message": "Conversion initialized" } ``` ## 4. List Conversions GET /merchant/conversions Retrieves a history of conversion transactions. ```json { "success": true, "data": [ { "quote_id": "quote:98a5d6d3-7cbc-4c7d-b4f6-d3bbbbe340b6", "debit_transaction_id": 2605, "credit_transaction_id": 2606, "status": "completed", "created_at": "2025-04-18T10:30:00.000000Z" } ], "message": "Conversions retrieved" } ``` ## 5. Dispute Conversion POST /merchant/conversions/{conversion_id}/dispute Allows a merchant to raise a dispute on a specific conversion transaction (e.g., if credit is delayed beyond SLA). **URL Parameters:** - `conversion_id` (integer, required): The ID of the conversion to dispute. **Request:** ```json { "reason": "Credit not received after SLA." } ``` --- ## Generate a Quote URL: https://docs.crayfi.com/conversions/generate-quote Before converting, you must generate a quote. The quote locks in the conversion rate for a specific duration (default: 10 minutes). | Method | URL | | ------ | --------------- | | POST | /merchant/quote | ### Request Body Payload | Parameter | Description | | --------------------- | ------------------------------------------------------------------ | | source_currency | The currency you are converting from. Example: `NGN` | | destination_currency | The currency you are converting to. Example: `USD` | | source_amount | The amount in the source currency to be converted. Example: `1500` | --- ## Execute Conversion URL: https://docs.crayfi.com/conversions/execute-conversion Finalizes the conversion using a valid quote_id obtained from the “Generate a Quote” endpoint. | Method | URL | | ------ | ----------------------------- | | GET | /merchant/conversions/convert | ### Query Parameters | Parameter | Description | | --------- | ----------------------------------------------------------------------------------- | | quote_id | The unique identifier for the quote, obtained from the "Generate a Quote" endpoint. | --- ## List Conversions URL: https://docs.crayfi.com/conversions/list-conversions Retrieves a history of conversion transactions. | Method | URL | | ------ | --------------------- | | GET | /merchant/conversions | This endpoint supports pagination via query parameters `page` and `per_page`. --- ## Dispute Conversion URL: https://docs.crayfi.com/conversions/dispute-conversion Allows a merchant to raise a dispute on a specific conversion transaction (e.g., if credit is delayed beyond SLA). | Method | URL | | ------ | --------------------------------------------- | | POST | /merchant/conversions/{conversion_id}/dispute | ### Path Parameters | Parameter | Description | | --------------- | ---------------------------------------- | | `conversion_id` | The ID of the conversion to be disputed. | --- ## Get Specific Exchange Rate URL: https://docs.crayfi.com/conversions/get-specific-exchange-rate Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/rates` Retrieves the current exchange rate, Service Level Agreement (SLA), and settlement type for a specific currency pair. --- ## Get Rates by Destination Currency URL: https://docs.crayfi.com/conversions/get-rates-by-destination Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/rates/destination` Retrieves all available exchange rates for a given destination currency. --- ## Generate a Quote URL: https://docs.crayfi.com/conversions/generate-quote-endpoint Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/quote` Before converting, you must generate a quote. The quote locks in the conversion rate for a specific duration (default: 10 minutes). --- ## Execute Conversion URL: https://docs.crayfi.com/conversions/execute-conversion-endpoint Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/conversions` Finalizes the conversion using a valid quote_id obtained from the “Generate a Quote” endpoint. --- ## Query Conversions URL: https://docs.crayfi.com/conversions/query-conversions Method: `GET` Endpoint: `GET https://pay.connectramp.com/api/conversions` Retrieves a history of conversion transactions. --- ## Dispute Conversions URL: https://docs.crayfi.com/conversions/dispute-conversions-endpoint Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/conversions/{conversion_id}/dispute` Allows a merchant to raise a dispute on a specific conversion transaction (e.g., if credit is delayed beyond SLA). --- # Refunds ## Refund URL: https://docs.crayfi.com/refunds The general functionality that enables a merchant to return funds to a customer after a successful payment is called the Refund System or Refund Processing. This is a critical component of a payment platform like Cray Finance, which provides capabilities for merchants to manage these reversals. ## Supported Currencies * **USD**: United States Dollar * **ZMW**: Zambian Kwacha * **GHS**: Ghanaian Cedi * **XOF**: West African CFA franc * **NGN**: Nigerian Naira ## Initiate The Initiate endpoint is your first step to easily getting money back to a customer! It's super simple: just send a POST request to /v2/refund/initiate. It only requires the customer reference of the original successful transaction in the request body, and instantly returns a status response telling you whether the refund process has been successfully initiated. This endpoint is essential for processing customer refunds quickly and programmatically! | Method | URL | | ------ | --- | | POST | /refund/initiate | ### Request Body Payload | 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" | | reference | A unique identifier for the initiated refund transaction. Example: "A74HULEKBXCRGQ2" | ## Partial Refund The Initiate endpoint is how you easily send back just a portion of a customer's original payment! It's super helpful for programmatically managing customer refund workflows, especially when only part of the goods or services are being returned. Just send a POST request to /v2/refund/initiate with the customer reference of the original transaction and the specific refund amount you want to return in the request body. The system processes the request and sends back a status to let you know the partial refund has been successfully initiated! | Method | URL | | ------ | --- | | POST | /refund/initiate | ### Request Body Payload | 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" | | 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" | ## Check Refund Status The GET Query endpoint is your quick and easy way to check on any refund you've initiated! It allows you to instantly retrieve all the details and the current status of a specific refund just by using its reference ID as a path variable ( /v2/refund/query/:reference ). This functionality is super useful for tracking the refund process in real-time, helping your business monitor everything seamlessly and provide accurate updates to your customers! | Method | URL | | ------ | --- | | GET | /refund/query/:reference | --- ## Initiate Refund URL: https://docs.crayfi.com/refunds/initiate-refund Method: `POST` Endpoint: `POST https://pay.connectramp.com/api/v2/refund/initiate` This endpoint allows you to initiate a full or partial refund for a transaction. --- ## Check Refund Status URL: https://docs.crayfi.com/refunds/check-refund-status Method: `GET` Endpoint: `GET https://pay.connectramp.com/api/v2/refund/query/{reference}` The GET Query endpoint is your quick and easy way to check on any refund you’ve initiated! It allows you to instantly retrieve all the details and the current status of a specific refund just by using its reference ID as a path variable ( /v2/refund/query/:reference ). This functionality is super useful for tracking the refund process in real-time, helping your business monitor everything seamlessly and provide accurate updates to your customers! ---