Hosted Payment Page

The hosted page workflow is our recommended way of accepting card payments. The merchant initiates a request and in response is given a URL to which the user is redirected to complete the payment.

Overview

Before starting, your merchant account needs to have been enabled to do funds collections via card in the specified supported countries. We equally recommend that you go through the Getting Started section to have a high-level understanding of the funds collection process.

When the initial API request is successful, a payment URL is returned, and the customer will be redirected to this URL where they'll be guided to complete the transaction. During the process, the customer will fill a card payment form and submit for processing. Depending on the authorization scheme, the customer will be navigated accordingly so that they can complete the payment

Step 1: Form the payment request payload

The table below describes the request parameters that are used for the collection/charge request. Most/all will be collected from the paying customer.

Parameter
Type
Required
Description

merchant_reference

String

true

The unique reference for this request. It must be at least 8 characters long. Alternatively, the value auto can be passed, and a unique reference will be created for you by the API

transaction_method

String

true

The transaction method to be used. This will be CARD for this request

currency

String

true

The 3-character ISO currency code for the request currency

amount

Number

true

The amount being requested

provider_code

String

true

The provider code as obtained from the payment options list

customer_name

String

false

The name of the customer

customer_email

String

false

The email of the customer

description

String

true

The description/narration for the transaction. Between 10-30 characters

charge_customer

Boolean

false

Whether or not the customer should bear the charge for the transaction. By default, this is false to mean that the merchant bears the charge.

allow_final_status_change

Boolean

false

Whether or not the final transaction status can be altered as described here. By default, this is true to mean Qwaap will alter the final transaction status under the circumstances described.

redirect_url

String

true

The HTTPs redirect URL to which the API will redirect when the payment is successful/failed

After collecting the necessary card payment information from your customer, prepare your request payload as demonstrated below.

{
    "merchant_reference": "auto",
    "transaction_method": "CARD",
    "currency": "NGN",
    "amount": 1000,
    "provider_code": "local_ngn",
    "customer_email": "[email protected]",
    "customer_name": "JOHN DOE",
    "description": "Test Collection",
    "charge_customer": false,
    "allow_final_status_change": true,
    "redirect_url": "https://your-redirect-url"
}

POST https://sandboxapi.qwaap.com/collections/initialize

The request is sent as a JSON body as demonstrated by the sample request below. Sample responses (acknowledgement and failure) are also shared.

curl -X POST "https://sandboxapi.qwaap.com/collections/initialize" \
   -H 'Content-Type: application/json' \
   -H "x-api-version: 1" \
   -H "public-key: your-public-key" \
   -d '{
        "merchant_reference": "auto",
        "transaction_method": "CARD",
        "currency": "NGN",
        "amount": 1000,
        "provider_code": "local_ngn",
        "customer_email": "[email protected]",
        "customer_name": "JOHN DOE",
        "description": "Test Collection",
        "charge_customer": false,
        "allow_final_status_change": true,
        "redirect_url": "https://your-redirect-url"
    }'
{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "QWAAPYSTHVTY7FKSE4Z",
        "merchant_reference": "MCTREF68SPABA2G7BWXE",
        "payment_url": "https://devpay.qwaap.com/pay/collection/QWAAPYSTHVTY7FKSE4Z"
    }
}

Step 2: Redirect to Payment URL

Notice the payment_url parameter in the callback body. The URL should be loaded in the browser so that the customer can proceed with the transaction. When the page loads, the customer will be guided through the payment process and on success/failure, the customer will be redirected to the redirect_url sent by the merchant in the request. Additionally, a callback/webhook will be sent to the configured collection callback URL.

Step 3: Handle the redirect and/or callback

Redirect

On success/failure of the transaction, the customer will be redirected to the URL that was passed in the redirect_url request parameter. The sample requests below demonstrated the success and failure scenarios. You can copy the URL and paste it on this online resource in order to view the query parameters therein.

https://webhook.site/85e18720-aa89-4f18-9db4-21c135642b46?id=34810&event=transaction.completed&merchant_reference=MCTREF68SPABA2G7BWXE&internal_reference=QWAAPYSTHVTY7FKSE4Z&transaction_type=COLLECTION&transaction_status=COMPLETED&status_message=Transaction%20Completed%20Successfully&rsa_signature=CG1ZuVzJMiNwLZEwaHGTvlvBW0ANOa2gncpEU29E5C%2BmSq9%2FUG9VoUr4DDfRfbabXJNmn5jQ98vqgAumIf%2FkKSfGbT7BoNk0X5q6kc1glWc%2FpVFramtPMQRMx39RqgQiPb1Y6wXS0AZmfopeD9IaQJCbicYpM2h23bT56iC9h2wVMIazu%2FeXu%2BZP%2FFoG5jG8utUUDxMHTLe1SMqorFsHkSoqvnRZWuDJZd36gCEogqqnN2Xui2rIjvznhHWdRwaftS9TRlT3ECm3QaIWyRh3Hw2zZ3apN73RjxPIHabDbUKwK0LgqGNtRA6XbBDDGl0tXCt0yIrunextt7XQ928oUMAykhiRYQaIWUbAvVQCrTFUx3K3ZCpnLJ4dBSK3EOnwVCLonxFgGzuoE69op7mf0IKdxU82mr7J1p%2FY6KiJB4I63EtIOouFteYNyVrNPcBHK%2Btd1TX5C39zOqzszDlJogQV0i3gSiMUJZmFysUpriSGT1I6kX3zaC2ac1znDsViHp%2B%2FB2pqYP9y3ggHyRkgKJBAkCu1Fnv%2BQ4YF2ESbFCESoI1ahsw8MvsthSZqN%2BKlMuxk%2F0tEZRbMLtNGcfQ6qqLKJlneony6xCKqAtUjjyr7Xydv4%2BC3HA3QoV3KRXr5n%2FzP6Pp6cG4e7nN8zGOoKlk8HXciav6Qz4GJlVIZwnE%3D&hmac_signature=t%3D1723816532379%2Cs%3D4e60eed65c566a0a9155aac084da8270c5dc826188d5d16785f0c6f6d5b1782d

Callback/Webhook

Every merchant account is expected to have configured a callback/webhook URL for collections. For all collections that transition to the final state (COMPLETED, FAILED or CANCELLED), a JSON POST request will be made to the callback URL. Sample callback payloads (request bodies) are shared below. Be sure to check out Handling Notifications to see how you should verify the signature(s) in the request headers and how to respond.

{
    "event": "transaction.completed",
    "payload": {
        "id": 20760,
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
        "internal_reference": "QWAAPYSTHVTY7FKSE4Z",
        "transaction_type": "COLLECTION",
        "request_currency": "NGN",
        "transaction_amount": 1000,
        "transaction_currency": "NGN",
        "transaction_charge": 100,
        "transaction_account": "462200XXXXXX5678",
        "charge_customer": false,
        "total_credit": 900,
        "provider_code": "local_ngn",
        "request_amount": 1000,
        "customer_name": "JOHN DOE",
        "institution_name": "Local Verve Card",
        "transaction_status": "COMPLETED",
        "status_message": "Transaction Completed Successfully"
    }
}

Either of the two (redirect/callback) can be used to confirm the final status of the transaction. We recommend that in either situation, the redirect/callback request is verified (by verifying the signatures)

PreviousCard PaymentsNextDirect Card Payment (S2S)

Last updated