Manage Direct Bank Transfer payment

Manage your Direct Bank Transfer payments.

After the successful charge transaction, you can perform additional operations on the payment resource. Some of the important ones are described in the following section.

For a full reference of managing payments, go to relevant server-side integration documentation page: Manage API resources (direct API calls), Manage API resources (PHP SDK), or Manage API resources (Java SDK).

Settlement Confirmation Flow

Direct Bank Transfer uses a settlement confirmation flow. Receipts are deferred until actual fund settlement is confirmed. The payment lifecycle is as follows:

Stage	Payment status	Charge status	Description
After customer pays	`completed`	`pending`	Customer has completed payment on bank portal. Funds are not yet settled.
After settlement confirmed	`completed`	`success`	Bank settlement confirmed. Funds received by Unzer.
Settlement timeout	`completed`	`failed`	Bank settlement not received within 7 days.
Late settlement recovery	`completed`	`success`	Payment previously marked as failed recovers if late settlement arrives.

Settlement timeline

Typical: Settlement confirmation arrives within 1 business day.
Maximum: Up to 7 days. If no settlement is received within 7 days, the charge transaction is marked as failed with reason SETTLEMENT_TIMEOUT.

Webhook notifications

The charge.succeeded webhook is sent only after settlement is confirmed, not immediately after the customer completes payment. Plan your order fulfillment logic accordingly:

payment.completed: Sent after the customer finishes the payment successfully.
charge.pending: Sent when the charge transaction is in pending state (before and after customer payment). Funds are awaiting settlement.
charge.succeeded: Sent after bank settlement is confirmed (typically +1 business day).
charge.failed with SETTLEMENT_TIMEOUT: Sent if settlement is not received within 7 days.
charge.succeeded (recovery): Sent if a previously timed-out payment is later settled.

Note

Do not fulfill orders based solely on the charge.pending event. Wait for the charge.succeeded webhook before considering the payment fully successful.
Subscribe to the charge.failed event to handle the SETTLEMENT_TIMEOUT scenario and notify customers accordingly.
Late settlements can recover a failed charge to success. Subscribe to charge.succeeded to handle this recovery scenario.

Get additional transaction data

You can get the payment details by using the getPayment call. This provides you with the payment status along with all the relevant data. For more information about the getPayment call, go to the API reference.

Within the transactions Array of the charge transaction, there is a specific section dedicated for the additional transaction data. This section contains important insights regarding the settlement status of the payment.

GET https://api.unzer.com/v1/payments/{paymentId}
...
transactions: [
...
  {
    "additionalTransactionData":
    {
     "onlineTransfer":
       {"targetDueDate": "2025-01-24T08:12:35.633Z"}
    }
  }
]

Field name	Description
`additionalTransactionData`	When a payment is settled, the following structure is included into the response of the `getPayment` call.
`onlineTransfer`	This key indicates that the payment was processed through an online transfer method.
`targetDueDate`	This field specifies the date and time when the payment was credited to the Unzer bank account. The format follows the ISO 8601 standard, ensuring clarity and consistency.

Note

Please be aware that funds can only be transferred after the settlement date has been set. The settlement date acts as the trigger for the funds transfer at Unzer, and any subsequent transfers to the merchant’s bank account will occur after this date.
To facilitate this process, you can request the settlement date by making a GET request. You can also subscribe to the webhook event type=all. To learn more, go to Supported webhook events

Cancel after payment (refund)

You can refund up to the amount of the received payment. To do this, you have to make a cancel transaction for an existing charge transaction.

POST https://api.unzer.com/v1/payments/s-pay-1/charges/s-chg-1/cancels

{
  "amount" : "20.000",
  "paymentReference": "Test cancel transaction"
}

$unzer = new Unzer('s-priv-xxxxxxxxxx');
$charge = $unzer->fetchChargeById('s-pay-1', 's-chg-1');
$cancel = $charge->cancel();

Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Cancel cancel = unzer.cancelCharge("s-pay-1", "s-chg-1");

In certain exceptional situations, we may be unable to provide the IBAN, requiring you to ask the customer to provide it once more. As a result, a URL will be included in the refund request. This feature will be implemented at a later stage.

UnzerAI

Welcome to UnzerAI!