Question: What are the base URLs for Kora's test and live environments?
Answer:
Test/Sandbox Environment: https://api.korapay.com/sandbox/
Live/Production Environment: https://api.korapay.com/
Question: What is the fundamental difference between Test and Live modes?
Answer:
Test Mode: A sandbox environment for building and testing integrations without touching real money. It uses test API keys. All transactions are simulated.
Live Mode: The production environment for processing real transactions with actual money. It requires live API keys, which are only available after the merchant's account has been activated and KYC is complete.
Question: What are the two types of API keys and how are they used?
Answer:
Public Key: Prefixed pk_. It is used for client-side operations, primarily for initializing the Kora Checkout standard library on the frontend. It is safe to expose in client-side code.
Secret Key: Prefixed sk_. It is used for all server-side API calls. It must be kept confidential and stored securely on the server. Never expose the Secret Key in any client-side code.
Question: How is the Secret Key used for authentication?
Answer: The Secret Key must be passed as a Bearer token in the Authorization header of every server-side API request. Format: Authorization: Bearer sk_test_your_secret_key_here
Question: How can a developer test their integration? What tools are available?
Answer: Developers must use the Test Mode with their test API keys. Kora provides a set of test cards and specific bank account numbers that can be used to simulate various transaction scenarios. For Checkout integrations, test payments can be made directly on the checkout modal. For API-based integrations, developers should use tools like Postman or write scripts to hit the sandbox API endpoints.
Question: Where can a developer find the test card details?
Answer: The full list of test cards for simulating successful payments, failed payments (e.g., insufficient funds), and 3D Secure authentication is available in the "Testing Your Integration" section of the developer documentation.
Question: What is the purpose of a webhook in the Kora ecosystem?
Answer: Webhooks are the primary mechanism Kora uses to send real-time, asynchronous notifications to a merchant's server about events that happen on their account. This is crucial for events that are not instantaneous, such as the final success or failure of a bank transfer payment or the resolution of a chargeback. Merchants should rely on webhooks as the definitive source of truth for transaction status.
Question: What does a typical webhook event payload look like?
Answer: All webhook events follow a standard JSON structure like this:
JSON
{
"event": {
"type": "charge.success",
"id": "evt_123456789"
},
"data": {
// Object containing details of the event
// For charge.success, this will be the transaction object
},
"customer": {
// Customer object associated with the event
}
}
Question: How should a developer secure their webhook endpoint?
Answer: This is critical. A developer must verify the webhook signature. Every webhook event sent by Kora includes a Kora-Signature header. The developer must compute their own signature using the received payload and their Secret Key (using an HMAC-SHA256 algorithm) and compare it to the signature in the header. If they don't match, the request should be rejected. This prevents processing of fraudulent webhook events not sent by Kora.
Question: What response should a developer's server return upon successfully receiving a webhook?
Answer: The server must respond with a 200 OK status code. Any other response code will be interpreted by Kora as a failure to deliver the webhook. Kora will attempt to resend a failed webhook multiple times with an exponential backoff strategy.
Question: What is the standard structure of an error response from the Kora API?
Answer: Error responses use standard HTTP status codes and a JSON body with a consistent structure:
JSON
{
"status": false,
"message": "A human-readable error message.",
"errors": {
"code": "ERROR_CODE_SLUG",
"message": "A more detailed error message.",
"attribute": "field_that_caused_the_error"
}
}
Question: What does the VALIDATION_ERROR code indicate?
Answer: This is a common error indicating that the API request failed because some of the data provided was invalid or missing. The errors object will contain details about which specific field (attribute) caused the problem, for example, an invalid email format or a missing required currency.
Question: What are the two main types of Checkout integration?
Answer:
Checkout - Standard: A JavaScript-based modal that pops up on the merchant's website. The merchant adds the Kora JS library to their site, and initiates the checkout with their Public Key and transaction details. The customer never leaves the merchant's site.
Checkout - Redirect: The merchant makes a server-side API call to generate a checkout_url. They then redirect their customer to this Kora-hosted payment page to complete the transaction. This is simpler and requires no frontend JavaScript integration.
Question: What is the API endpoint to create a checkout redirect link?
Answer: POST - https://api.korapay.com/merchant/api/v1/charges/initialize
The request body must include amount, currency, customer details, and a redirect_url where the customer will be sent after the payment attempt.
Question: What are Payment Links?
Answer: Payment Links are shareable links for collecting payments, created from the Kora dashboard. They are a no-code solution. When a customer clicks the link, they are taken to a Kora-hosted page to complete the payment. This is ideal for merchants without a website or for collecting payments via social media or invoices.
Question: What is the API endpoint to create a dedicated NGN Virtual Bank Account?
Answer: POST - https://api.korapay.com/merchant/api/v1/virtual-bank-account
The request body requires a customer object containing at least the name and email of the customer for whom the account is being created.
Question: How is a merchant notified of a payment made to a Virtual Bank Account?
Answer: Through a webhook with the event type charge.success. The webhook payload will contain the full transaction object, including the amount paid and the customer details associated with that virtual account.
Question: How should a developer handle underpayments or overpayments to a Virtual Account?
Answer:
Underpayments: Kora's system will still fire a charge.success webhook with the amount that was actually paid. The merchant's business logic must then compare the amount_paid to the amount_expected and decide how to proceed (e.g., partially fulfill the order, contact the customer to pay the balance).
Overpayments: The same charge.success webhook is sent with the overpaid amount. The merchant's system should detect the surplus and decide how to handle it (e.g., credit the customer's wallet, process a partial refund for the excess amount).
Question: What is the recommended way to accept card payments for PCI compliance?
Answer: The recommended method is Checkout (Standard or Redirect). In these flows, the sensitive card details are entered directly on Kora's secure elements, and the merchant's server never touches the raw card data. The merchant's server then receives a charge_reference after the customer completes the payment, which can be used to verify the transaction status.
Question: For advanced use cases, how can a developer accept card payments directly via API?
Answer: This requires a higher level of PCI compliance. The process is typically:
Use a frontend library to tokenize the card details on the client-side.
Send the resulting token to the merchant's server.
The server makes a POST /charge/card request to the Kora API (https://api.korapay.com/merchant/api/v1/charges/card), including the token, amount, currency, and customer details.
Question: What is the "Flexible Card Payments" API?
Answer: This refers to the ability to charge a card using a saved card token from a previous transaction, enabling recurring payments or subscriptions. The POST - https://api.korapay.com/merchant/api/v1/charges/card endpoint can be used with a token that represents a saved card instead of a one-time charge token.
Question: What is the key difference between "Pay with Bank - Direct Debit" and a standard "Bank Transfer"?
Answer:
Bank Transfer: A "push" payment. The customer must manually initiate the transfer from their bank app to a destination account provided by Kora.
Direct Debit: A "pull" payment. After a one-time authorization from the customer, the merchant can programmatically pull funds from the customer's bank account for future payments.
Question: How is a Mobile Money payment initiated via API?
Answer: POST - https://api.korapay.com/merchant/api/v1/charges/mobile-money
The request body must include the amount, currency (e.g., GHS, KES, XOF, XAF), customer details, and a payment_details object containing the phone_number and network of the mobile money wallet. An OTP will typically be sent to the customer's phone to authorize the transaction.
Question: What is the API endpoint to get the status or history of pay-ins?
Answer:
Fetch all transactions: GET - {{base_url}}/merchant/api/v1/pay-ins?limit=10
(This supports pagination parameters like page and per_page).
Fetch a single transaction: GET - https://api.korapay.com/merchant/api/v1/charges/:{transaction_reference}
Question: What is the API endpoint to initiate a refund?
Answer: https://api.korapay.com/merchant/api/v1/refunds/initiate
POST method
Question: What information is required to process a refund via the API?
Answer: The request body requires the transaction_reference of the original charge you wish to refund. You can also specify an amount if you want to process a partial refund. If no amount is specified, a full refund will be initiated.
Question: What is the difference between a "Payout" and a "Withdrawal"?
Answer: In the context of the Kora API, these terms are often used interchangeably to describe the process of sending money from the merchant's Kora wallet to an external destination, such as a customer's bank account.
Question: What is the API endpoint for initiating a single payout?
Answer: POST - https://api.korapay.com/merchant/api/v1/transactions/disburse
The request body must include a destination object specifying the type (e.g., bank_account), amount, currency, and the recipient's details (e.g., account_number, bank_code).
Question: How is a Bulk Payout initiated via API?
Answer: POST - https://api.korapay.com/merchant/api/v1/transactions/disburse/bulk
The request body requires a payouts key, which is an array of payout objects. Each object in the array represents a single payout and contains the destination, amount, and currency for that specific recipient.
Question: Is there a limit to the number of payouts in a single bulk API call?
Answer: Yes, the documentation specifies a limit on the number of payouts that can be included in a single array. The tech support team should refer to the "Bulk Payouts via API" page for the exact current limit (e.g., 500 payouts per call).
Comments
0 comments
Please sign in to leave a comment.