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.