KorapayClient

`korapay_client.KorapayClient`

Bases: BaseClient

Synchronous client for interfacing with Korapay

`authorize_card_charge(transaction_reference, authorization)`

Authorize a pending charge on a debit card.

Parameters:

Name	Type	Description	Default
`transaction_reference`	`str`	The reference to the pending charge returned as a response by korapay when the charge was initiated.	required
`authorization`	`Authorization`	A pydantic model with additional fields for authorizing the charge. The required field may vary depending on the type of authorization required. E.g., if a pending charge requires a pin for authorization `Authorization(pin='<customer-pin>')` is sufficient. Please refer to Korapay's Official documentation. The `Authorization` model can be imported directly from `korapay_client`	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`authorize_mobile_money_charge(reference, token)`

Authorize a payment via mobile money.

After initiating a charge via mobile money, the next step is based on the auth model returned in the response to the charge initiation. There are two ways of authorizing a transaction OTP and STK_PROMPT. After making the request to charge the number, if the status of the transaction is processing and auth_model is OTP, this means an OTP has been sent to the wallet owner's phone. You would need to collect the OTP to authorize the transaction. Collect the OTP sent to the customer’s phone and call this method with the OTP and the transaction reference. If the OTP verification is successful, an STK prompt will be sent to the wallet owner's phone for him to enter his PIN.

Parameters:

Name	Type	Description	Default
`reference`	`str`	The reference to the transaction.	required
`token`	`str`	the otp or token from the customer.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`authorize_stk(reference, pin)`

Authorize STK prompts in test/development.

This method allows you to authorize the transaction in the Sandbox environment. It is meant to simulate a wallet owner entering their wallet PIN at the STK prompt.

Parameters:

Name	Type	Description	Default
`reference`	`str`	The reference of the pending transaction.	required
`pin`	`str`	The simulated customer's pin	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`bulk_payout_to_bank_account(batch_reference, description, merchant_bears_cost, currency, payouts)`

Initiate a bulk payout to bank accounts.

Parameters:

Name	Type	Description	Default
`batch_reference`	`str`	A reference used to identify the batch.	required
`description`	`str`	A narration for the batch.	required
`merchant_bears_cost`	`bool`	This sets who bear the fees of the transaction. If it is set to `True`, the merchant will bear the fee. If it is set to `False`, the customer will bear the fee. By default, it is `False`.	required
`currency`	`Currency`	A enum representing the currency to disburse in. E.g., `Currency.NGN`	required
`payouts`	`list[PayoutOrder]`	A list of `PayoutOrder` which is a pydantic model representing individual recipient information in the bulk payout. This model can be imported directly from `korapay_client`	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`charge_via_bank_transfer(reference, customer_email, amount, currency, customer_name=None, account_name=None, narration=None, notification_url=None, merchant_bears_cost=False, metadata=None)`

Accept payments via bank transfers.

Parameters:

Name	Type	Description	Default
`reference`	`str`	A unique reference for the payment. The reference must be at least 8 characters long.	required
`customer_email`	`str`	The email of your customer.	required
`amount`	`int \| float \| Decimal`	The amount for the charge.	required
`currency`	`Currency`	An enum representing the currency for the charge. E.g., `Currency.NGN`. Currently, the only supported currency is `Currency.NGN`	required
`customer_name`	`str \| None`	The name of your customer.	`None`
`account_name`	`str \| None`	The account name that should be displayed when the account number is resolved.	`None`
`narration`	`str \| None`	Information/narration about the transaction.	`None`
`notification_url`	`str \| None`	A URL to which we can send the webhook notification for the transaction.	`None`
`merchant_bears_cost`	`bool`	This sets who bear the fees of the transaction. If it is set to `True`, the merchant will bear the fee. If it is set to `False`, the customer will bear the fee. By default, it is `False`.	`False`
`metadata`	`dict \| None`	A dictionary with a maximum of 5 fields/keys for storing additional information. Empty dictionaries are not allowed. Each field name (i.e., dictionary keys) can have a maximum length of 20 characters. Allowed characters: A-Z, a-z, 0-9, and -.	`None`

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`charge_via_card(reference, customer_name, customer_email, card, amount, currency, redirect_url=None, metadata=None)`

Accept debit card payments.

Parameters:

Name	Type	Description	Default
`reference`	`str`	A unique reference for the payment. The reference must be at least 8 characters long.	required
`customer_name`	`str`	The name of your customer.	required
`customer_email`	`EmailStr`	The email of your customer.	required
`card`	`Card`	A pydantic model representing your customer's card information. it can be imported directly from `korapay_client`.	required
`amount`	`int \| float \| Decimal`	The amount for the charge.	required
`currency`	`Currency`	An enum representing the currency for the charge. E.g., `Currency.NGN`	required
`redirect_url`	`HttpUrl \| None`	A URL to which we can redirect your customer after their payment is complete.	`None`
`metadata`	`dict \| None`	A dictionary with a maximum of 5 fields/keys for storing additional information. Empty dictionaries are not allowed. Each field name (i.e., dictionary keys) can have a maximum length of 20 characters. Allowed characters: A-Z, a-z, 0-9, and -.	`None`

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`charge_via_mobile_money(reference, customer_email, amount, mobile_money_number, currency, notification_url=None, customer_name=None, redirect_url=None, merchant_bears_cost=False, description=None, metadata=None)`

Accept payments via mobile money.

Note

Korapay currently only supports payments in Kenyan Shillings and Ghanaian Cedis. For Kenya, they support the following wallets; Mpesa, Airtel, and Equitel. While in Ghana, they support MTN Momo and Airtel Tigo.

Parameters:

Name	Type	Description	Default
`reference`	`str`	A unique reference for the payment. The reference must be at least 8 characters long.	required
`customer_email`	`str`	The email of your customer.	required
`amount`	`int \| float \| Decimal`	The amount for the charge.	required
`mobile_money_number`	`str`	The mobile number of the customer to be charged e.g., 254700000000.	required
`currency`	`Currency`	An enum representing the currency the payment should be made in e.g., `Currency.KES`.	required
`notification_url`	`str \| None`	The webhook URL to be called when the transaction is complete.	`None`
`customer_name`	`str \| None`	The name of your customer.	`None`
`redirect_url`	`str \| None`	A URL to which we can redirect your customer after their payment is complete.	`None`
`merchant_bears_cost`	`bool`	This sets who bear the fees of the transaction. If it is set to `True`, the merchant will bear the fee. If it is set to `False`, the customer will bear the fee. By default, it is `False`.	`False`
`description`	`str \| None`	Information/narration about the transaction.	`None`
`metadata`	`dict \| None`	A dictionary with a maximum of 5 fields/keys for storing additional information. Empty dictionaries are not allowed. Each field name (i.e., dictionary keys) can have a maximum length of 20 characters. Allowed characters: A-Z, a-z, 0-9, and -.	`None`

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`create_virtual_bank_account(account_name, account_reference, bank_code, customer_name, bvn, customer_email=None, nin=None)`

Create a virtual bank account.

Virtual Bank Accounts (or Virtual Accounts) are a special type of bank account that you can use to receive payments from your customers multiple times.

Parameters:

Name	Type	Description	Default
`account_name`	`str`	The name of the Virtual Bank account.	required
`account_reference`	`str`	Your unique reference to identify a virtual bank account.	required
`bank_code`	`str`	This is the bank code of the bank providing the virtual bank account. E.g., `035` is the code for Wema Bank. Use `000` to create a virtual bank account in the sandbox environment.	required
`customer_name`	`str`	The customer's name.	required
`bvn`	`str`	The Bank Verification Number (BVN) of the customer.	required
`customer_email`	`str \| None`	The customer's email address.	`None`
`nin`	`str \| None`	The National Identity Number (NIN) of your customer.	`None`

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`credit_sandbox_virtual_bank_account(account_number, amount, currency)`

Create a virtual bank account for testing/development.

Parameters:

Name	Type	Description	Default
`account_number`	`str`	This is the account number of the Fixed Virtual Bank Account.	required
`amount`	`int \| float \| Decimal`	This is the amount you want to credit to the account. The minimum amount is NGN 100, and the maximum amount is NGN 10,000,000.	required
`currency`	`Currency`	An enum representing the currency for the account. Only `Currency.NGN` is accepted for now.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`get_balances()`

Retrieve all your pending and available balances.

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`get_banks(country)`

Retrieve a list of all banks supported by Korapay and their properties.

Parameters:

Name	Type	Description	Default
`country`	`Country`	An enum representing the country to retrieve the banks from. E.g., `Country.NIGERIA`.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`get_bulk_transaction(bulk_reference)`

Retrieve the transactions in a bulk payout

Parameters:

Name	Type	Description	Default
`bulk_reference`	`str`	The reference of the bulk payout whose transactions you to retrieve.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`get_charge(reference)`

Retrieve a charge.

Parameters:

Name	Type	Description	Default
`reference`	`str`	The reference of the charge.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`get_mmo(country)`

Retrieve a list of all mobile money operators supported by Korapay and their properties.

Parameters:

Name	Type	Description	Default
`country`	`Country`	An enum representing the country to retrieve the MMOs from. E.g., `Country.GHANA`.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`get_payout_transaction(transaction_reference)`

Retrieve the status and details of a disbursement through the reference.

This method can be used to verify the status of a payout transaction.

Parameters:

Name	Type	Description	Default
`transaction_reference`	`str`	The reference of the payout.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`get_payouts(bulk_reference)`

Retrieve a bulk payout.

Parameters:

Name	Type	Description	Default
`bulk_reference`	`str`	The reference of the bulk payout to retrieve.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`get_virtual_bank_account(account_reference)`

Retrieve a virtual bank account.

Parameters:

Name	Type	Description	Default
`account_reference`	`str`	Your unique reference for the virtual bank account.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`get_virtual_bank_account_transactions(account_number)`

Retrieve transactions associated with a virtual bank account.

Parameters:

Name	Type	Description	Default
`account_number`	`str`	The account number of the virtual account.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`initiate_charge(reference, amount, currency, narration, notification_url, customer_email, customer_name=None, channels=None, default_channel=None, redirect_url=None)`

Initiate a charge on your customer supporting multiple payment channels.

This method allows you to configure payment channels of your choice when initiating a payment.

Parameters:

Name	Type	Description	Default
`reference`	`str`	Your transaction reference. Must be unique for every transaction.	required
`amount`	`int \| float \| Decimal`	The amount to charge the customer.	required
`currency`	`Currency`	An enum representing the currency to charge the customer in. E.g., `Currency.GHS`.	required
`narration`	`str`	The description of the transaction.	required
`notification_url`	`str`	The webhook URL to be called when the transaction is complete.	required
`customer_email`	`str`	The customer's email.	required
`customer_name`	`str \| None`	The customer's name.	`None`
`channels`	`list[PaymentChannel] \| None`	A list of `PaymentChannel` enum representing the payment channels you want to support for accepting the payments. E.g., `[PaymentChannel.CARD, PaymentChannel.BANK_TRANSFER]`	`None`
`default_channel`	`PaymentChannel \| None`	A enum representing the preferred payment channel when multiple payment channels are supported. E.g., `PaymentChannel.MOBILE_MONEY`	`None`
`redirect_url`	`str \| None`	The URL to redirect your customer when the transaction is complete.	`None`

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`payout_to_bank_account(reference, amount, currency, bank_code, account_number, customer_email, narration=None, customer_name=None)`

Initiate a single disbursement to a bank account.

Parameters:

Name	Type	Description	Default
`reference`	`str`	Unique transaction reference.	required
`amount`	`int \| float \| Decimal`	The transaction amount.	required
`currency`	`Currency`	A enum representing the currency to disburse in. E.g., `Currency.NGN`	required
`bank_code`	`str`	The Recipient bank code. Bank_codes on testmode with Test keys to simulate a successful transaction are 044, 033, 058 i.e., Access, UBA and GTB respectively, other banks would simulate a failed transaction on testmode with testkeys.	required
`account_number`	`str`	The recipient's account number.	required
`customer_email`	`str`	The customer's email.	required
`narration`	`str \| None`	The transaction's narration or description.	`None`
`customer_name`	`str \| None`	The customer's name.	`None`

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`payout_to_mobile_money(reference, amount, currency, mobile_money_operator, mobile_number, customer_email, customer_name=None, narration=None)`

Initiate a single disbursement to a mobile money account.

Parameters:

Name	Type	Description	Default
`reference`	`str`	Unique transaction reference.	required
`amount`	`int \| float \| Decimal`	The transaction amount.	required
`currency`	`Currency`	A enum representing the currency to disburse in. E.g., `Currency.NGN`	required
`mobile_money_operator`	`MobileMoneyOperator \| str`	An enum or str representing the mobile money operator. E.g., `MobileMoneyOperator.AIRTEL_KENYA`.	required
`mobile_number`	`str`	The recipient's mobile money number.	required
`customer_email`	`str`	The customer's email.	required
`customer_name`	`str \| None`	The customer's name.	`None`
`narration`	`str \| None`	The transaction's narration or description.	`None`

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`resend_card_otp(transaction_reference)`

Resend one time password/pin for pending transaction.

Parameters:

Name	Type	Description	Default
`transaction_reference`	`str`	The reference to the pending charge returned as a response by korapay when the charge was initiated.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`resend_mobile_money_otp(transaction_reference)`

Resend one time password/pin for a pending mobile money transaction.

This method allows you to resend OTP in a situation where the initial OTP received had expired or was not received at all.

Parameters:

Name	Type	Description	Default
`transaction_reference`	`str`	The reference of the pending transaction.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`resend_stk(transaction_reference)`

Resend STK prompt.

This method allows you to resend the STK prompt in a situation where the initial STK prompt received had expired or was not received at all.

Args: transaction_reference: The reference of the pending transaction.

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.

`resolve_bank_account(bank_code, account_number)`

Resolves a bank account.

This method can be used to validate if an account number is valid for the specified bank.

Parameters:

Name	Type	Description	Default
`bank_code`	`str`	The code for the bank the account number belongs to.	required
`account_number`	`str`	The account number to be resolved.	required

Returns:

Type	Description
`Response`	A pydantic model containing the result of the request.

Raises:

Type	Description
`ClientError`	When an error or exception occurs while making the request to Korapay.