---
updatedAt: 2026-07-01T07:56:54.000Z
agentTools:
  projectIndex: https://docs.dpopay.com/dpo-pay-by-network/llms.txt
---

# Push Payments Callback

Receive automatic pushPayments notifications from DPO after successful payments and return OK to acknowledge them.

# 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:

1. Receive the XML payload from DPO.
2. Read the transaction and customer details from the payload.
3. Update the transaction status in your system.
4. 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
<?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
<?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
<?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.                 |

<br />