DPO Pay Microservice

Overview

This microservice handles DPO Pay payment token creation and verification. It provides secure endpoints to create payment tokens and verify transaction status with bearer token authentication.

API Endpoints

POST /api/payment/create-token - Create payment token

POST /api/payment/verify-token - Verify transaction status

Authentication Required: Both endpoints require a valid Bearer token in the Authorization header.

Create Token Request Body

{
  "amount": 100.00,
  "currency": "USD",
  "customerName": "John Doe",
  "customerEmail": "john.doe@example.com",
  "customerPhone": "+254712345678",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "customerAddress": "123 Main Street",
  "customerCity": "Nairobi",
  "customerCountry": "KE",
  "customerZip": "00100",
  "customerDialCode": "KE",
  "description": "Payment for services",
  "reference": "REF-12345",
  "redirectUrl": "https://your-domain.com/payment/complete",
  "backUrl": "https://your-domain.com/payment/cancel"
}

Verify Token Request Body

{
  "transactionToken": "72983CAC-5DB1-4C7F-BD88-352066B71592",
  "verifyTransaction": 1,
  "accRef": "ABC123REF",
  "customerPhone": "123456789",
  "customerPhonePrefix": "254",
  "customerEmail": "john.doe@example.com"
}

Required: Either transactionToken OR companyRef

Optional: All other fields are optional for additional updates

verifyTransaction: 1 = Verify transaction, 0 = Don't verify (query only)

Verify Token Parameters Explained

verifyTransaction Parameter

By default, the system will verify the transaction and mark it as "website verified" in DPO systems. This parameter controls the verification behavior:

1 (Verify): Marks the transaction as "website verified" in DPO systems. Use this when you have successfully processed the payment and want to confirm completion.
0 (Don't Verify): Only queries the transaction status without marking as verified. Use this to check payment status first, then call again with value 1 after processing.

Recommended Workflow: First call with verifyTransaction: 0 to check the payment status and process the transaction details. Then call again with verifyTransaction: 1 to mark as verified once you've successfully processed the client's payment.

Important: You must verify the token within 30 minutes of transaction completion, otherwise DPO Pay will send an alert email to the provider.

Create Token Required Fields (ALL fields are mandatory)

amount - Payment amount
currency - Currency code (USD or XOF only)
customerName - Customer full name
customerEmail - Customer email address
customerPhone - Customer phone number
customerFirstName - Customer first name
customerLastName - Customer last name
customerAddress - Customer street address
customerCity - Customer city
customerCountry - 2-letter ISO country code
customerZip - Postal/ZIP code
customerDialCode - 2-letter ISO country code
description - Payment description
reference - Unique payment reference
redirectUrl - URL to redirect after payment completion
backUrl - URL to let customer go back from payment page

Supported Currencies

Note: This service only accepts payments in USD (US Dollar) and XOF (West African CFA Franc).

URL Parameters Explained

RedirectURL

URL where the customer is redirected after payment completion. DPO Pay will append these GET parameters:

TransID - Transaction reference
CCDapproval - Approval number
PnrID - Customer reference
TransactionToken - Transaction reference
CompanyRef - Your reference

BackURL

URL for the back button on the payment page. DPO Pay will append these GET parameters:

TransactionToken - Transaction reference
CompanyRef - Your reference

Responses

Create Token Success Response

{
  "success": true,
  "token": "57466282-EBD7-4ED5-B699-8659330A6996",
  "reference": "REF-12345",
  "paymentUrl": "https://secure.3gdirectpay.com/payv3.php?ID=57466282-EBD7-4ED5-B699-8659330A6996"
}

Verify Token Success Response

{
  "success": true,
  "result": "000",
  "resultExplanation": "Transaction paid",
  "customerName": "John Doe",
  "customerCredit": "4432",
  "transactionApproval": "938204312",
  "transactionCurrency": "USD",
  "transactionAmount": "950.00",
  "fraudAlert": "000",
  "fraudExplanation": "No Fraud detected",
  "transactionNetAmount": "945",
  "transactionSettlementDate": "2013/12/31",
  "customerPhone": "254123456789",
  "customerCountry": "KE",
  "customerAddress": "Stranfe blvd.",
  "customerCity": "Nairobi",
  "customerZip": "AH1",
  "accRef": "ABC123REF"
}

Error Response

{
  "success": false,
  "error": "Error message describing the issue"
}

Usage Examples

Create Token

curl -X POST https://your-domain.com/api/payment/create-token \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-token-here" \
  -d '{
    "amount": 100.00,
    "currency": "USD",
    "customerName": "John Doe",
    "customerEmail": "john.doe@example.com",
    "description": "Payment for services",
    "reference": "REF-12345",
    "redirectUrl": "https://your-domain.com/payment/complete",
    "backUrl": "https://your-domain.com/payment/cancel"
  }'

Verify Token

curl -X POST https://your-domain.com/api/payment/verify-token \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-token-here" \
  -d '{
    "transactionToken": "72983CAC-5DB1-4C7F-BD88-352066B71592",
    "verifyTransaction": 1
  }'