Skip to content

Scenario

The customer pays for a service using DeltaPay. The service provider is notified of updates regarding the transaction, such as the success or failure of the payment.

For example, the process of paying for an item online might look like this:

  1. The website asks for the user's phone number or username used on DeltaPay. This information may also be linked to the user's profile.
  2. The website sends a payment request to the user including at least the amount, recipient account, and reference (see Payment Requests). The website may optionally specify a timeout within which the payment request must be accepted.
  3. The user either accepts or rejects the payment request. They can only accept requests where the resulting transaction would be possible.
  4. Once the transaction settles, the IPN (Instant Payment Notification) is sent to the registered callback(s), notifying the seller of an update regarding the payment.

Using QR codes

  1. The website generates a payment QR code encoding the amount, recipient, and reference (see QR Code Specification).
  2. The user scans the QR code and the information is prefilled in the DeltaPay app.
  3. The user approves and sends the transaction.
  4. The IPN is sent to the registered callback(s), notifying the seller of an update regarding the payment.

Note: We are working on supporting deep-links as an alternative to QR code or manual input.

Payment reference

There are two options for encoding a payment reference:

  • notes: can be entered and edited by the user (max 200 characters)
  • metadata: is not shown to the user

Both are arbitrary strings that can be included in the QR code and will be picked up by the DeltaPay app.

Instant Payment Notification (IPN)

The IPN callback is triggered for all updates to transaction statuses involving either the sender or recipient account. For more detailed information about callbacks, refer to this section.

Callback URL format:

base URL + /transaction/ipn

Example payload

{
  "transaction_id": 398,
  "transaction_type": "rent",
  "transaction_status": "succeeded",
  "initialisation_time": "2024-10-26T20:43:15.515122",
  "settled_time": "2024-10-26T20:43:21.639949",
  "note": "hello",
  "metadata": null,
  "source_of_funds": "",
  "bank_account": null,
  "sender_account_id": 1014,
  "sender_account_name": "New 3",
  "sender_name": "DeltaPay",
  "sender_till_name": null,
  "sender_phone_country_dialcode": null,
  "sender_phone_number": null,
  "recipient_account_id": 1001,
  "recipient_account_name": "Personal",
  "recipient_name": "adrian",
  "recipient_till_name": null,
  "recipient_phone_country_dialcode": null,
  "recipient_phone_number": null,
  "amount": 6,
  "cashback_received": 0,
  "cashback_spent": 0,
  "fee": 0,
  "commission_amount": 0,
  "signature": "VMDnRnvRJVvTHu9HNgjsIWhlXOd1bYkPPsp23y3cVl3Tn7Zzlg7AJAy5654fld5U7XrhQbDd3Mj684WcFnpbRgeiRIQDBtEL2eLKO7ZHjC/jg0n0zVjE2TRfPACuiXsmR/pJG+8hPmABBqThGj2hE5SEBFD4WSlzgAcLA0ZxZWvtDu2FAUpN1B+FtMfCmxa4DmH/GPtVs+80c8hHX3KGt35iaBrwD66vhdEUrSaYEgFooRmS3K9dm+neOPHgIfXG60sv03Ru5EZDMKNQvalUlCdLUerjr3eoZPs4DkYZj2FhwBZOJPBh6SDmCgSUsKclvepd0hExXNsRwOsKsxDcuQ=="
}

Payment Request Status Updates

This callback is triggered whenever a payment request status changes for any request where the recipient account is the one associated with the registered callback. For more detailed information about callbacks, refer to this section.

Callback URL format:

base URL + /payment-request/update

Example payload

{
  "payment_request_id": 191,
  "payment_request_status": "rejected",
  "account_id": 14,
  "transaction_type": "eating_out",
  "transaction_id": null,
  "transaction_status": null,
  "till_name": null,
  "till_id": null,
  "note": "Peter ist ein netter Mensch",
  "metadata": null,
  "request_time": "2025-09-19T18:23:40.577917",
  "timeout": null,
  "sender_user_id": null,
  "sender_legal_entity_id": 2,
  "recipient_user_id": 76,
  "sender_name": "MinenhleGrocery",
  "recipient_name": "Sifiso Dlamini (@philipp20251)",
  "amount": 22,
  "signature": "iNUd7WxPOlYXdIsjwWi2MGHoYuAKwVvSl5TBQCXzduW5G0Wk8NYTffRuenJmh33Q3WW3sjDme4lfX376EmnHcynZMnN0IJDY0ZF6+KGQObWa22teeRw5RVBzuzosyY5rHzOz8w/JhZII8b/86qPLvYGcgfYU3eClbnJ3nAYdD5NxYDVFgAYo0/WrvqVgGsx+QVpa/ofY+ylkBpraiDGugPS4DOJM85Xl40fwCRq7QHbb8gLpYUFm4Ny6hR+iKr6TPrzIN54arQRjWbgOMSwHUv1QEAGfH+CW66RIkXgj8PqaUGYdtD57aXwa3Lo8IMaq1SJ/8chvaWV4I2rE3QsNPA=="
}

Fallback mechanisms

Callbacks are the most efficient way to receive real-time updates, but they rely on your endpoint being continuously available. If a callback cannot be delivered, it will currently not be retried.

In such cases, clients can use polling as a fallback:

This ensures that your system can recover state even if a callback was missed.