Accept Flexible Card Payments with API
Korapay enables merchants to accept flexible card payments through advanced card operations such as Pre-Authorization, single and multiple Captures, Void Captures, Void authorization, and Refunds. This guide walks you through each of these processes and explains how to make the most of them using our APIs.
Pre-requisites
- Before you start, ensure that your account on Korapay is activated.
- Card payments need to be enabled on your account before you can start accepting such payments. Reach out to our team at [email protected] with a request to allow card payments on your account.
- To make use of our Card APIs, you are also required to be PCI DSS certified (Level 1).
Pre Authorization
This API operation allows you to place a lien on an amount on the card for some time. Once this action has been carried out successfully, the amount remains unavailable to the cardholder until expiry or it has been voided
To use this endpoint, encrypt your charge details by following the steps listed below;
Statement Descriptor
Merchants can customize the description that appears on the cardholder's bank statement by using a dynamic_descriptor
. This helps to ensure that the cardholder can recognize the transaction. The dynamic descriptor is limited to 10 alphanumeric characters (A-Z, 0-9), and no special characters are allowed. This can be added to the encryption payload.
curl --request POST \
--url https://api.korapay.com/merchant/api/v1/charges/card/pre-authorize \
--header 'Authorization: Bearer YOUR_KORAPAY_SECRET_KEY' \
--data '{
"charge_data": c62ac600880756fa9456e812dbbaccc8:14ed28362057615390765db7eb6a9f4630f12d23c67ad462621cd7e8cc:f2197fe1911162010cefa3038a12188f}'
{
"status": true,
"message": "success",
"data": {
"amount": 10,
"total_authorized_amount": 10,
"total_captured_amount": 0,
"total_refunded_amount": 0,
"currency": "NGN",
"payment_reference": "auth_payment_ref_55486648601",
"transaction_reference": "auth_transaction_ref_14318822981",
"auth_model": "NO_AUTH",
"response_message": "Operation completed successfully",
"status": "pre_authorized",
"charge_operation": "pre_authorization",
"pre_auth_expiry": "2024-09-05 04:07:38",
"metadata": {
"gateway_code": "00",
"receipt": "424914235206",
"stan": "235206"
},
"card": {
"card_type": "mastercard",
"first_six": "523046",
"last_four": "6017",
"expiry": "06/29"
}
}
}
Use case
Zero Auth
It may be desirable for you as a merchant to confirm a card's validity without actually charging the card. We refer to this as Zero Auth. A zero base amount, like NGN0 or NGN0.1, is charged momentarily before being instantly canceled. This procedure verifies that the card is active and prepared for use in the future.
Capture
After authorizing a transaction, you can capture the full funds at once or in multiple stages.
You can make multiple partial captures until the full authorized amount is captured, or the authorization expires
The payment_reference should be the payment reference used during the pre-authorization step.
curl --location 'https://api.korapay.com/merchant/api/v1/charges/card/capture' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk_live_**** \
--data '{
"amount": "3",
"currency": "NGN",
"payment_reference": "auth_payment_ref_55486648601",
"transaction_reference": "capture_transaction_ref_41125937954"
}'
{
"status": true,
"message": "Card charged successfully",
"data": {
"amount": 3,
"amount_charged": 3,
"total_authorized_amount": 10,
"total_captured_amount": 3,
"total_refunded_amount": 0,
"currency": "NGN",
"fee": 0.23,
"vat": 0.02,
"payment_reference": "auth_payment_ref_55486648601",
"transaction_reference": "capture_transaction_ref_41125937954",
"status": "success",
"charge_operation": "capture",
"pre_auth_expiry": "2024-09-05 04:07:38",
"response_message": "Card charged successfully",
"metadata": {
"gateway_code": "00",
"receipt": "424914235206",
"stan": "236286"
},
"card": {
"card_type": "mastercard",
"first_six": "523046",
"last_four": "6017",
"expiry": "06/29"
}
}
}
Use case
Flexible order processing
You can choose to capture funds incrementally as different milestones of an order or service are fulfilled
Void
This operation allows you to cancel a capture or pre-authorization transaction that has not yet been settled by Korapay.
Void operation can only be performed on unsettled transactions. If multiple captures are made, the capture before the most recent capture is treated as a settled transaction. This means to successfully void auth, you need to have just one capture after the auth
curl --location 'https://api.korapay.com/merchant/api/v1/charges/card/void' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk_live_*****' \
--data '{
"payment_reference": "auth_payment_ref_55486648601",
"transaction_reference": "void_transaction_ref_8878739831",
"target_transaction_reference": "capture_transaction_ref_41125937954"
}'
{
"status": true,
"message": "Authorization voided successfully",
"data": {
"amount": "10.00",
"total_authorized_amount": 0,
"total_captured_amount": 0,
"total_refunded_amount": 0,
"currency": "NGN",
"payment_reference": "auth_payment_ref_55486648601",
"target_transaction_reference": "auth_transaction_ref_14318822981",
"transaction_reference": "void_transaction_ref_37239989472",
"response_message": "Operation completed successfully",
"status": "void_capture",
"charge_operation": "void_authorization",
"pre_auth_expiry": "2024-09-05 04:07:38",
"metadata": {
"gateway_code": "00",
"receipt": "424914235206",
"stan": "236353"
},
"card": {
"card_type": "mastercard",
"first_six": "523046",
"last_four": "6017",
"expiry": "06/29"
}
}
}
Use case
Void can also be used to test a card’s validity. An auth request can be made for a nominal amount and then immediately voided. See Zero Auth for more details
Refund
Refunds are applicable only for settled transactions. You can request a partial or full refund on settled transactions.
curl --location 'https://api.korapay.com/merchant/api/v1/charges/card/refund \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk_live_*****' \
--data '{
"amount": "3",
"currency": "NGN",
"payment_reference": "auth_payment_ref_55486648601",
"transaction_reference": "void_transaction_ref_8878739831",
"target_transaction_reference": "capture_transaction_ref_41125937954"
}'
{
"status": true,
"message": "Authorization voided successfully",
"data": {
"amount": "10.00",
"total_authorized_amount": 0,
"total_captured_amount": 0,
"total_refunded_amount": 0,
"currency": "NGN",
"payment_reference": "auth_payment_ref_55486648601",
"target_transaction_reference": "auth_transaction_ref_14318822981",
"transaction_reference": "void_transaction_ref_37239989472",
"response_message": "Operation completed successfully",
"status": "void_capture",
"charge_operation": "void_authorization",
"pre_auth_expiry": "2024-09-05 04:07:38",
"metadata": {
"gateway_code": "00",
"receipt": "424914235206",
"stan": "236353"
},
"card": {
"card_type": "mastercard",
"first_six": "523046",
"last_four": "6017",
"expiry": "06/29"
}
}
}
Use case
Chargeback
When a customer disputes a transaction and requests a chargeback, the full or partial refund of the disputed amount can be sent back to the card.
Updated about 2 months ago