Push Payments Callback

Receive an automatic pushPayments notification from DPO after a successful payment and return OK to acknowledge it.

DPO sends the notification to the URL provided for your merchant account after a successful payment. Use this callback to update your system when a transaction is paid.

Usage

The pushPayments API notifies the merchant for each successful payment.

Your callback endpoint should:

Receive the XML payload from DPO.
Read the transaction and customer details from the payload.
Update the transaction status in your system.
Return OK in the XML response to confirm that the push payment was received.

Response requirement

The merchant must return OK to approve and confirm the push payment notification.

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Response>OK</Response>
</API3G>

Push notification parameters

The server pushes the pushPayments API notification using the following parameters.

Parameter	Data type	Description
`Result`	3-digit code	Code sent with the result of the request.
`ResultExplanation`	Text	Free text result explanation.
`TransactionToken`	Token	Transaction token.
`TransactionRef`	Text	Reference sent during the `createToken` API request.
`CustomerName`	Text	Customer name as entered on the 3GDirectpay payment page.
`CustomerCredit`	Text	Last 4 digits of the credit card. Sent if the transaction was paid by credit card.
`CustomerCreditType`	Text	Credit card type.
`TransactionApproval`	Text	Transaction approval number.
`TransactionCurrency`	Text	Final payment currency. The customer can convert the payment.
`TransactionAmount`	Money	Paid amount.
`FraudAlert`	3-digit code	Fraud code according to the fraud codes table.
`FraudExplnation`	Text	Free text fraud analysis.
`TransactionNetAmount`	Money	Net transaction amount.
`TransactionSettlementDate`	Date	Transaction settlement date.
`TransactionRollingReserveAmount`	Money	Transaction rolling reserve amount.
`TransactionRollingReserveDate`	Date	Rolling reserve release date.
`CustomerPhone`	Text	Customer phone number.
`CustomerCountry`	Text	Customer country.
`CustomerAddress`	Text	Customer address.
`CustomerCity`	Text	Customer city.
`CustomerZip`	Text	Customer ZIP code.
`MobilePaymentRequest`	Text	Mobile payment request status.
`AccRef`	Text	Internal accounting reference number.

Push notification example

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Result>000</Result>
  <ResultExplanation>Transaction paid</ResultExplanation>
  <TransactionToken>68B90B5E-25F6-4146-8AB1-G5B3A0C41N9E</TransactionToken>
  <TransactionRef>A123BEWDSD</TransactionRef>
  <CustomerName>John Doe</CustomerName>
  <CustomerCredit>4432</CustomerCredit>
  <TransactionApproval>938204312</TransactionApproval>
  <TransactionCurrency>USD</TransactionCurrency>
  <TransactionAmount>950.00</TransactionAmount>
  <FraudAlert>000</FraudAlert>
  <FraudExplnation>No Fraud detected</FraudExplnation>
  <TransactionNetAmount>945</TransactionNetAmount>
  <TransactionSettlementDate>2013/12/31</TransactionSettlementDate>
  <TransactionRollingReserveAmount>5</TransactionRollingReserveAmount>
  <TransactionRollingReserveDate>2014/12/31</TransactionRollingReserveDate>
  <CustomerPhone>254123456789</CustomerPhone>
  <CustomerCountry>KE</CustomerCountry>
  <CustomerAddress>Stranfe blvd.</CustomerAddress>
  <CustomerCity>Nairobi</CustomerCity>
  <CustomerZip>AH1</CustomerZip>
  <MobilePaymentRequest>Sent</MobilePaymentRequest>
  <AccRef>ABC123REF</AccRef>
</API3G>

Callback response variables

Return these variables from your callback endpoint.

Parameter	Data type	Description	Required
`Response`	Text	Must return `OK` to confirm the push payment.	Mandatory
`CompanyRef`	Text	Company reference number. Can update the transaction `CompanyRef` on callback.	Optional
`AccRef`	Text	Internal accounting reference number. Can update the transaction `AccRef` on callback.	Optional

Callback response example

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Response>OK</Response>
</API3G>

Fraud alert codes

Code	Explanation
`000`	Genuine transaction.
`001`	Low risk. Not checked.
`002`	Suspected fraud alert.
`003`	Fraud alert cleared. Merchant marked as clear.
`004`	Suspect fraud alert.
`005`	Fraud alert cleared. Genuine transaction.
`006`	Black. Fraudulent transaction.