Direct Card Payment (S2S)
Another way to accept card payments is by using our server-to-server workflow. The detailed guide below will show you how to successfully charge cards on DusuPay using our APIs.
Overview
Before starting, your merchant account needs to have been enabled to do funds collections via card in the specified supported options. Supported card options are shown here.
We equally recommend that you go through the Getting Started section to have a high-level understanding of the funds collection process.
You're required to be PCI DSS certified (Level 1) in order to use the direct card charge workflow.
PCI DSS Compliance
The Payment Card Industry Data Security Standard (PCI DSS) is a set of global security standards designed to ensure that all entities that process, store or transmit cardholder data and/or sensitive authentication data maintain a secure environment. PCI DSS sets a baseline level of protection for consumers and helps reduce fraud and data breaches across the entire payment ecosystem. It is applicable to any organization that accepts or processes payment cards. Learn more here.
Step 1: Collect the card payment data
After collecting the necessary card and payment information from your customer, prepare your data object to look like the example shown below. In this payload, you may choose to pass your user’s PIN or not. The purpose of this JSON is to prepare the card data for encryption since the request doesn't expect it in plain text. The outcome of the encryption will be value sent in a special parameter named card_cipher, which is sent alongside the main collection API request
{
"first_name": "John",
"last_name": "Doe",
"card_no": "4622000000005678",
"exp_month": "06",
"exp_year": "22",
"cvv": "123",
"billing_address": "Second Street",
"billing_city": "San Francisco",
"billing_zip": "94105",
"billing_state": "CA",
"billing_country": "US"
}
Step 2: Encrypt the card JSON data
DusuPay ensures the complete security of card data in transit by using RSA encryption. The stringified payment data from Step 1 must be encrypted using the DusuPay Public Key before making the collection request. To encrypt the JSON string correctly, we have organized a few code samples to illustrate how it could be done as shown below.
Copy the public key for the environment you're working with from here. This document assumes that the public key would be stored somewhere on your server under the name dusupay.public.key.pem
<?php
function encryptJSON($jsonString, $publicKeyPath) {
$publicKey = file_get_contents($publicKeyPath);
$pubKeyId = openssl_pkey_get_public($publicKey);
openssl_public_encrypt($jsonString, $encrypted, $pubKeyId);
return base64_encode($encrypted);
}
// Example usage
$jsonData = json_encode(['first_name' => 'John', 'last_name' => 'Doe', 'card_no' => '4622000000005678', 'exp_month' => '06', 'exp_year' => '2024', 'cvv' => '123', 'billing_address' => 'Second Street', 'billing_city' => 'San Francisco', 'billing_zip' => '94105', 'billing_state' => 'CA', 'billing_country' => 'US']);
$publicKeyPath = 'path-to-file/dusupay.public.key.pem';
try {
$encryptedData = encryptJSON($jsonData, $publicKeyPath);
echo "Encrypted data: " . $encryptedData;
} catch (Exception $e) {
echo "Encryption failed: " . $e->getMessage();
}
?>
Step 3: Form the payment request payload
The table below describes the request parameters that are used for the collection/charge request. The encrypted string from Step 2 will be sent as part of the request as described in the table below.
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
customer_name
String
false
The name of the customer
customer_email
String
false
The email of the customer
card_cipher
String
true
The resultant string after encryption above
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 DusuPay 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,
"card_cipher": "*******",
"redirect_url": "https://your-redirect-url"
}
POST
https://sandboxapi.dusupay.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.dusupay.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,
"card_cipher": "*******",
"redirect_url": "https://your-redirect-url"
}'
{
"code": 202,
"status": "accepted",
"message": "Request Accepted",
"data": {
"internal_reference": "DUSUPAYZAERK2SBE6WJAG",
"merchant_reference": "MCTREFQSSBHMHU3RCTLA",
"payment_url": "https://devpay.dusupay.com/pay/collection/DUSUPAYZAERK2SBE6WJAG"
}
}
Step 4: 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 5: 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/cc0393dc-fe49-401b-ba56-da9e099a3648?id=33911&event=transaction.completed&merchant_reference=MCTREFZQTUDRC38TLYUV&internal_reference=DUSUPAYHYJQ3ZUJMPGFG5&transaction_type=COLLECTION&transaction_status=COMPLETED&status_message=Transaction%20Completed%20Successfully&rsa_signature=Y23aNOaOs6NfOnrhpZrWGAOI4bMR5kNobFnrOBlqF%2FY7f03aBpHZx2rcmU3q2P9zS2w61xs3FsT%2FipRI9F21dNJ0UxDQci7yQ%2B7CZbk6kJQbfX9Ht7OIhH2%2F7cv%2FNUXDmXzZQYST3Qwe9QIhea1SIImWRzR8HKAeEeoVRPLDqxohLX4A0S91hjrZVO%2BjohZJLazIeXFrOaJyIu3xPQ7bzJi%2BfVhw6ry3R7NknIj5y752WpW0CqvxXKr3wPUIXy99tnN%2FCWLG65AmVL9GkBZj0j12%2B8ztBpknPBuGKWxndJB7zkkPTCmA%2BA1m21f3RENYTNH7nHet5zp5Iyq%2BkmtVVUmEcfvfAwAxs0sP0fYTFU8iSX6wvB6UEvk3AWgrprlb1XGd3sRgFgCb3HjzA7%2B8RBi%2Fw59qIXqK4LlbOtZw2tPc7MjLeXq%2BmqzrO8SRxyuvu6lX0HPhaHSXAGq%2BvljA1Kk4ZNLdSWxYCC2IgI7%2BPomrfWW1I6pNIF%2BudPTIYTPN6EEdMUwFBltyAoh%2ByHl6K%2F%2Fcz4FfE6OgZwJkbQ8661sHqiB2ND%2FhSQh%2B0Qre1tQTLx7BGQTSGdD34CLn%2FQICIlqNCvKbMF4ZO208xYaBct01T6Xa23zykkrmlTviEMJgSIo3zj2KpN%2BTF1X5jZOXLszBL20o1SeQlY9%2BhRzshzY%3D&hmac_signature=t%3D1721639784089%2Cs%3D1ec4e0f7749397faea80958bca9ab2c6d8e7448c3ee02f958881a392ce299128
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": "DUSUPAYRMGRXNNYBWATKJ",
"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"
}
}
Last updated