Charge a payment

Transfer money form the customer to the merchant.

Overview

The charge resource is used for activating the flow of transferring the money from the customer to you (merchant). When the customer initiates a payment, based on your configuration, a direct charge request or authorization request is created. You can either charge directly or authorize the payment and then charge it later.

Check Payment methods page to see what payment methods support direct charge (most do) and charge after authorization.

Charge directly

Direct charge will debit customer’s account without any prior authorization.

A direct charge is triggered by calling /payments/charges with an amount, currency, order ID, and a reference to a payment method.

POST https://api.unzer.com/v1/payments/charges
{
    "amount": "200",
    "currency": "EUR",
    "returnUrl": "http://www.unzer.com/de",
    "orderId": "{{random_payment_orderId}}",
    "resources": {
        "typeId": "{{payment_method_id}}"
    }
}
Parameter Type Description
amount (required) string Specify the amount to be charged. It is rounded off depending on the respective currency.
currency (required) string(3) Specify the ISO currency code: For a full list of codes, see Amounts and Currencies.
returnUrl (conditional) string Specify the URL the customer must be redirected to after a transaction.

Required for redirect payment methods.
orderId string Specify the order ID for the payment. This is required for referencing to the transaction later.
resources (conditional) string Based on your setup, specify the other details that you want to add to the payment.

Required for Direct charge for payment method reference

Not required for Charge after authorization, you can capture the full amount when you send an empty request.

For a full description of the /payments/charges call please refer to API reference guide.

{
    "id": "s-chg-1",
    "isSuccess": false,
    "isPending": true,
    "isError": false,
    "redirectUrl": "https://payment.unzer.com/v1/redirect/paypalot/s-DyFFeOswkkGu",
    "message": {
        "code": "COR.000.200.000",
        "merchant": "Transaction pending",
        "customer": "Your payment is currently pending. Please contact us for more information."
    },
    "amount": "200.0000",
    "currency": "EUR",
    "returnUrl": "http://www.unzer.com/de",
    "date": "2021-06-07 06:30:20",
    "resources": {
        "paymentId": "s-pay-134237",
        "traceId": "5cc09a0e9df0d281ec68310137d8b306",
        "typeId": "s-ppl-yuxdtvwktq8k"
    },
    "orderId": "payment-order-1623047439520-439",
    "paymentReference": "",
    "processing": {
        "uniqueId": "31HA07BC811A3F8482D02202AAFDDC72",
        "shortId": "4869.7381.7787",
        "traceId": "5cc09a0e9df0d281ec68310137d8b306"
    }
}

In the previous example , the charge ID is returned with the value s-chg-1. The status of the payment is returned with one of the following values as true:

Status parameter Description
isSuccess The charge call was executed successfully.
isPending The charge call may return a RedirectUrl. The customer must be redirected to the RedirectUrl so that the customer can complete the payment.
The payment method determines whether a charge call can enter the pending state.
isError Something went wrong. Response contains a separate section that describes the problem.

Only one of the three values can be true. If there is an error, an error code is displayed in the details with a message for you and the customer.

Parameter Type Description
id string ID of the charge transaction
isSuccess boolean If the transaction was successful, the value is set to true.
isPending boolean If the transaction is pending, the value is set to true. for example, if a redirect to an external system is required.
isError boolean If an error occurs, this value is set to true.
redirectUrl string If the customer’s confirmation is required, a redirect URL will be returned.
Customer needs to be redirected to this URL and proceed the confirmation.
message object
message.code string Every error returns a unique id.
message.customer string Error message for your customer translated into the customer language.
message.merchant string Error message for you. This message appears always in English.
amount string The charged amount. The amount is rounded depending on the respective currency.
currency string(3) ISO currency code.
returnUrl string The URL the customer will be redirected to after a transaction.
paymentReference string The description of the transaction.
date date Timestamp of this transaction.
resources object
resources.customerId string Customer ID used for this transaction.
resource.basketId string The basket ID used for this transaction.
resource.metadataId string The metadata ID used for this transaction.
resources.paymentId string ID of the payment.
resources.typeId string ID of the types Resource that is to be used for this transaction.
processing object
processing.uniqueId string Unique ID of the payment system used.
processing.shortId string The reference ID of the payment system.
processing.iban string Your (merchant) IBAN for prepayment or invoice. In case of direct debit, this value contains the customer IBAN.
processing.bic string Your (merchant) BIC for prepayment or invoice. In the case of a direct debit, this value contains the customer BIC.
processing.identification string This value returns the descriptor for invoice and prepayment.
processing.creatorId string This value returns your creditor ID.
processing.3dsecure boolean Indicates a 3DS transaction (card payment type only).

Charge after authorization

You can also have a two-step procedure in which you first authorize and then charge a payment.

To charge after authorization, you must specify the payment ID or the order ID in the request URL. You can charge the specified amount either partially or fully.

Authorization reserves an amount on the customer’s account. You have 7 days to charge this amount from the customer.

Option 1: Charge full amount

To charge the full amount, you can send an empty charge request after authorizing a payment.

POST https://api.unzer.com/v1/payments/{{payment_id}}/charges

{}
{
    "id": "s-chg-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "card3ds": true,
    "message": {
        "code": "COR.000.100.112",
        "merchant": "Request successfully processed in 'Merchant in Connector Test Mode'",
        "customer": "Your payments have been successfully processed in sandbox mode."
    },
    "amount": "100.0000",
    "currency": "EUR",
    "date": "2021-06-10 11:02:17",
    },
    ...
}

The charge response parameters are explained in the Charge directly section.

Option 2: Charge partial amount

You can also partially charge a payment. This is useful if you shipped some goods to the customer and only want to invoice the shipped goods. If you are charging partially, and charge more than the total charge amount, an error is displayed.

For example, you can charge 40 EUR for the total authorized amount of 100 EUR.

POST https://api.unzer.com/v1/payments/{{order_id}}/charges
{
"amount": "40.0000"
}
{
    "id": "s-chg-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "card3ds": true,
    "message": {
        "code": "COR.000.100.112",
        "merchant": "Request successfully processed in 'Merchant in Connector Test Mode'",
        "customer": "Your payments have been successfully processed in sandbox mode."
    },
    "amount": "40.0000",
    "currency": "EUR",
    "date": "2021-06-10 06:48:54",
    "resources": {
        "customerId": "",
        "paymentId": "s-pay-134249",
        "basketId": "",
        "metadataId": "",
        "payPageId": "",
        "traceId": "99817d01a889c9dde3b828b16aaa2445",
        "typeId": "s-crd-qiwdokmbequc"
    },
    ...
}

To check the pending amount, send a GET request for the order_ID. In the above scenario, 60 EUR is shown as the remaining amount.

{
    "id": "s-pay-134249",
    "state": {
        "id": 3,
        "name": "partly"
    },
    "amount": {
        "total": "100.0000",
        "charged": "40.0000",
        "canceled": "0.0000",
        "remaining": "60.0000"
    },
    "currency": "EUR",
    "orderId": "",
    "invoiceId": "",
    "resources": {
        "customerId": "",
        "paymentId": "s-pay-134249",
        "basketId": "",
        "metadataId": "",
        "payPageId": "",
        "traceId": "99817d01a889c9dde3b828b16aaa2445",
        "typeId": "s-crd-qiwdokmbequc"
    },
    ...
}

See also