Card Payments Integration

Learn how to accept debit and credit card payments through EcobankPay

Overview

Card payment integration with EcobankPay allows your customers to make payments using their credit or debit cards. The integration process follows these general steps:

1. Initialize a payment request to EcobankPay
2. Redirect the customer to the EcobankPay secure payment page
3. Customer enters card details and completes 3D Secure authentication if required
4. EcobankPay processes the payment and notifies your application
5. Verify the payment status using the status check endpoint

Integration Steps

1. Initiate Card Payment Request

To start a card payment, send a POST request to the EcobankPay card payment endpoint:

The request body must include the following required parameters:

Optional parameters that enhance the payment experience:

2. Creating the Secure Hash

The secure_hash is critical for card transactions to ensure request integrity. Create it using these steps:

1. Sort the request parameters alphabetically by parameter name
2. Concatenate the parameter name-value pairs as name=value
3. Apply HMAC SHA-256 using your merchant secret as the key
4. Convert the result to a hexadecimal string

// Parameters (sorted alphabetically)
description=Payment for Order #12345
invoice_id=INV12345
merchant_key=abcdef1234-f5d6-4931-8544-58dc97a5
total=10.00

// Concatenated string
"invoice_id=INV12345&merchant_key=abcdef1234-f5d6-4931-8544-58dc97a5&total=10.00"

// Apply HMAC SHA-256 with your merchant secret
secure_hash = HMAC_SHA256(concatenated_string, merchant_secret)

3. Sample Request

Here's an example of a card payment request:

POST https://pgw.paywithonline.com/v1/card_payments
Content-Type: application/json

{
  "merchant_key": "abcdef1234-f5d6-4931-8544-58dc97a5",
  "invoice_id": "INV12345",
  "total": 10.00,
  "description": "Payment for Order #12345",
  "email": "customer@example.com",
  "number": "+233201234567",
  "generate_checkout_url": true,
  "success_url": "https://yourwebsite.com/payment/success",
  "cancelled_url": "https://yourwebsite.com/payment/cancelled",
  "ipn_url": "https://yourwebsite.com/api/payment-webhook",
  "secure_hash": "d4f321f8fddd0e7cc24e5d9bc321ea5c25c6f05d44401f7fb0b9f2a3cc4c"
}

4. Response Handling

Upon successful submission, you'll receive a JSON response with payment details:

{
  "success": true,
  "url": "https://pgw.paywithonline.com/checkout/7785598425589933",
  "tx_reference": "ECO123456789",
  "message": "Payment process initiated"
}

The key parameters in the response:

• url: The checkout URL to redirect the customer to
• tx_reference: EcobankPay's unique transaction reference
• success: Indicates if the request was accepted (not payment completion)

5. Redirect the Customer

Redirect your customer to the URL provided in the response. This secure page will:

• Collect the customer's card details
• Implement 3D Secure verification if supported by the card issuer
• Process the payment and show the result to the customer

6. Payment Notification Handling

EcobankPay will notify your application about payment status in two ways:

• Redirect to your success_url or cancelled_url based on payment outcome
• POST request to your ipn_url with payment details and status (if provided)

7. Verify Payment Status

To verify the payment status, make a GET request to the transaction status endpoint:

The response will include the current transaction status:

{
  "status": "paid",
  "status_reason": "",
  "buyer_firstname": "John",
  "buyer_lastname": "Doe",
  "buyer_email": "customer@example.com",
  "buyer_phone": "+233201234567",
  "invoice_id": "INV12345",
  "amount": 10.00,
  "as_at": "2023-03-28T14:22:30Z",
  "narration": "Payment for Order #12345"
}

3D Secure Authentication

EcobankPay automatically handles 3D Secure authentication for eligible cards. This process:

• Provides an additional layer of security for online card transactions
• Requires the cardholder to complete an authentication step with their bank
• Reduces the risk of fraud and chargebacks
• Is fully managed by the EcobankPay checkout flow

No additional integration is required on your end to support 3D Secure - it's built into the card payment flow.

Error Handling

Common errors you might encounter during card payment integration:

Security Considerations

Additional security measures for card payments:

• Always use HTTPS for all communication with EcobankPay APIs
• Never store card details on your servers
• The secure_hash is critically important for card transactions - implement it properly
• EcobankPay's hosted checkout page is PCI-DSS compliant, minimizing your compliance burden
• Always verify payment status using the status check endpoint before fulfilling orders