alt

Important information

Please be advised that there will be a scheduled downtime across our API network on November 05 and November 07, 2024. For more information, visit our platform status portal.:
- Scheduled maintenance on November 5, 2024
- Scheduled maintenance on November 7, 2024

Unzer
search
Ctrl+K

    Accept PayPal Express with UI components

    Use Unzer UI component to add PayPal Express payments to your checkout page.

    Overview

    Using UI components for Paypal Express you create a payment type resource that is used to make the payment. You do not need any form fields for this payment method. You can check a demo version of the component here. Basic steps for integrating using UI components are the same for all payment methods and you can read about them here.

    Before you begin

    Step 1: Add UI components to your payment page
    client side

    First, you need to initiate our UI components library and add the payment form to your payment page.

    Initiate UI component

    Load our JS script and CSS stylesheet

    Include Unzer’s script and stylesheet on your website.

    Always load the script and stylesheet directly from Unzer:

    <link rel="stylesheet" href="https://static.unzer.com/v1/unzer.css" />
<script type="text/javascript" src="https://static.unzer.com/v1/unzer.js"></script>
    icon
    Faster load time
    To make your website load faster, insert JavaScript scripts at the bottom of your HTML document.
    icon
    Importing Unzer styles
    To minimize the risk of Unzer styles affecting the styles of your webpage, we suggest putting unzer.css on top of other imported CSS files.

    Create an Unzer instance

    Create an unzer instance with your public key:

    // Creating an unzer instance with your public key
var unzerInstance = new unzer('s-pub-xxxxxxxxxx');
    icon
    Placeholder keys
    In the previous example, we used a placeholder API key for example purposes. You should replace it with your public key.

    Localization and languages

    We support localization with locale option parameters. Check the Localization page for a list of all the supported locales.

    The auto option (applied by default) uses the client’s browser language.

    Here you can see how to set the language, in our case ‘de-DE’ - to do so, add a comma separated parameter to your unzer instance:

    // Creating an unzer instance with your public key
var unzerInstance = new unzer('s-pub-xxxxxxxxxx', {locale: 'de-DE'});

    Implement the payment form

    Because no additional data is required for this payment method, you only need to create a simple HTML button on the client side using the Create method:

    <div id="error-holder" class="field" style="color: #9f3a38">
    <!-- Errors will be inserted here -->
</div>
<div id="example-paypal-express"></div>
    icon
    A button is create and automatically rendered, so you do not need to place a Button tag because the Create method creates it.

    Matching IDs

    When choosing your ID for a UI component, make sure that the names in your HTML and JavaScript match.

    For example:

    <div id="example-PayPal"> matches containerId: "example-PayPal".

    Create a payment type resource

    To create a payment type resource – a PayPal Express instance, call the unzerInstance.PaypalExpress() method:

    // Creating an PayPal express instance
var paypalExpress = unzerInstance.PaypalExpress()

// Rendering PayPal Express button
paypalExpress.create({
  containerId: 'example-paypal-express'
});

    Add an event listener for “submit” of the form.

    Inside this, create a Promise on the PaypalExpress object. The Promise gets either resolved or rejected:

    paypalExpress.addEventListener('click', function() {
    paypalExpress.createResource()
        .then(function(result) {
            // Submit the id of the created payment type to your
            // backend to perform the payment transaction with it.
            typeId = result.id;
        })
        .catch(function(error) {
            // handle errors
            $('#error-holder').html(error.message)
        })
});

    Optional: Customize the UI components

    You can easily customize the color of the button by changing the options within the create method. Here you can set the following colors: blue(by default), white, silver, black, and gold.

    paypalExpress.create({
    containerId: 'example-paypal-express',
    color: 'gold'
});

    For more details on PayPal payment type creation, see API reference.

    Step 2: Create a basket resource
    server side

    The basket resource stores information about the purchased products, used vouchers, and the shipment costs.

    POST https://api.unzer.com/v2/baskets

Body:
{
  "currencyCode": "EUR",
  "orderId": "YourOrderId1234",
  "totalValueGross":195.90,
  "note": "basket note",
  "basketItems": [
    {
      "title": "Notebook pro",
      "basketItemReferenceId": "item-1",
      "quantity": 1,
      "amountPerUnitGross": 200.00,
      "amountDiscountPerUnitGross": 10.00,
      "vat": 1,
      "unit": "pc",
      "subTitle": "basket item 2",
      "type": "goods"
    },
    {
      "title": "Shipment costs",
      "basketItemReferenceId": "item-2",
      "quantity": 1,
      "amountPerUnitGross": 5.90,
      "vat": 1,
      "subTitle": "Insured standard shipment",
      "type": "shipment"
    }
  ]
}

    $unzer = new Unzer('s-priv-xxxxxxxxxx');

$basketItem = (new BasketItem())
    ->setBasketItemReferenceId('Item-d030efbd4963')
    ->setQuantity(10)
    ->setUnit('m')
    ->setAmountPerUnitGross(20.00)
    ->setAmountDiscountPerUnitGross(1.00)
    ->setVat(19.0)
    ->setTitle('SDM 6 CABLE')
    ->setSubTitle('This is brand new Mid 2019 version')
    ->setImageUrl('https://a.storyblok.com/f/91629/x/1ba8deb8cc/unzer_primarylogo__white_rgb.svg')
    ->setType(BasketItemTypes::GOODS);

$basket = (new Basket())
    ->setTotalValueGross(190.00)
    ->setCurrencyCode('EUR')
    ->setOrderId('Order-12345')
    ->setNote('Test Basket')
    ->addBasketItem($basketItem);

$unzer->createBasket($basket);

    BasketItem basketItem = new BasketItem()
        .setBasketItemReferenceId("Item-d030efbd4963")
        .setQuantity(BigDecimal.valueOf(10))
        .setUnit("m")
        .setAmountPerUnitGross(BigDecimal.valueOf(20.00))
        .setAmountDiscountPerUnitGross(BigDecimal.valueOf(1.00))
        .setVat(BigDecimal.valueOf(19.0))
        .setTitle("SDM 6 CABLE")
        .setSubTitle("This is brand new Mid 2019 version")
        .setImageUrl(new URL("https://a.storyblok.com/f/91629/x/1ba8deb8cc/unzer_primarylogo__white_rgb.svg"))
        .setType(BasketItem.Type.GOODS);

Basket basket  = new Basket()
        .setTotalValueGross(BigDecimal.valueOf(190.00))
        .setCurrencyCode(Currency.getInstance("EUR"))
        .setOrderId("Order-12345")
        .setNote("Test Basket")
        .addBasketItem(basketItem);

Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
unzer.createBasket(basket);

    The response looks similar to the following example:

    {
    "id": "s-bsk-12345"
}

    For a full description of basket resource, refer to the relevant server-side-integration documentation page.

    Step 3: Make a payment
    server side

    For PayPal Express, an extended 2-step process for PayPal Express is applicable. This is different from the standard PayPal transaction flow.

    In a first step, you are forwarding the customer to the PayPal payment page, where the customer authenticates himself and approves the order initially. Once this is successfully done, PayPal provides the customer’s full address data, that you can use to complete the customer’s order in your shop. With the address data, you can recalculate the shipping costs according to the now known shipping address.

    In a second step, you are finalizing the payment in a separate request to Unzer by providing the final transaction amount.

    Depending on your use cases, you have the option to use two different transaction flows.

    Option 1: You can charge the customer’s wallet directly and the payment is done once the customer confirmed the order, and you’ve successfully finalized the payment immediately during customer’s checkout. For more details, see Order fulfillment.

    Option 2: For a delayed fulfillment, you can authorize the payment first and the amount is blocked on the customer’s wallet. When you ship the customer’s order, you can then charge the blocked amount and charge the customer’s wallet. For more details, see Order fulfillment.

    For more details on managing PayPal payments, such as refunding them, see Manage PayPal payments.

    Option 1: Make a charge transaction

    Make a POST /payments/charges

    Now, make a charge transaction with the Paypal typeId that you created and the returnUrl leading back to your shop after the customer has successfully approved the order on the PayPal payment page. With the charge transaction, an amount is reserved but is not yet transferred. Initially the transaction is pending and a payment resource is created.

    POST https://api.unzer.com/v1/payments/charges

Body:
{
    "amount": "195.90",
    "currency": "EUR",
    "returnUrl": "https://unzer.com/",
    "paymentReference": "Example Reference",
    "orderId": "ExampleOrderId1234",
    "resources": {
        "typeId": "s-ppl-twq0jsaafyny",
        "basketId": "s-bsk-12345"
    },
    "additionalTransactionData": {
        "paypal": {
            "checkoutType": "express"
        }
    }
}

    $unzer = new Unzer('s-priv-xxxxxxxxxx');
$charge = (new Charge(195.9, 'EUR', 'https://unzer.com/'))
    ->setCheckoutType('express', $paypal)
    ->setPaymentReference("Example Reference")
    ->setOrderId("ExampleOrderId1234");
    
$unzer->performCharge($charge, $paypal, null, null, $basket);

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Charge charge = (Charge) new Charge()
    .setAmount(BigDecimal.valueOf(195.9))
    .setCurrencyCode(Currency.getInstance("EUR"))
    .setReturnUrl("https://unzer.com/")
    .setPaymentReference("Example Reference")
    .setOrderId("ExampleOrderId1234");
    .setAdditionalTransactionData(
      new AdditionalTransactionData()
        .setPaypal(new PaypalData().setCheckoutType(PaypalData.CheckoutType.EXPRESS))
    );
unzer.charge(charge);

    The response looks similar to the following example:

    {
    "id": "s-chg-1",
    "isSuccess": false,
    "isPending": true,
    "isError": false,
    "isResumed": false
    "redirectUrl": "https://sbx-payment.unzer.com/v1/redirect/paypal/s-ky7ZyEmKNjiC",
    "message": {
        "code": "COR.000.200.000",
        "merchant": "Transaction pending",
        "customer": "Your payment is currently pending. Please contact us for more information."
    },
    "amount": "195.9000",
    "currency": "EUR",
    "returnUrl": "https://unzer.com/",
    "date": "2022-10-31 12:48:12",
    "resources": {
        "customerId": "",
        "paymentId": "s-pay-8537",
        "basketId": "s-bsk-12345",
        "metadataId": "",
        "traceId": "f24acee84b5d28324489a7860bc7ffb2",
        "typeId": "s-ppl-skki29gw2fue"
    },
    "additionalTransactionData": {
        "paypal": {
            "checkoutType": "express"
        }
    },
    "orderId": "YourOrderId1234",
    "paymentReference": "Example Reference",
    "processing": {
        "uniqueId": "31HA07BC8137FFAF17A41E1EADC47133",
        "shortId": "5311.4688.9455",
        "traceId": "f24acee84b5d28324489a7860bc7ffb2"
    }
}

    Fetch the result of POST /payments/charges

    We recommend subscribing to the charge event to receive notifications about any changes to the charge transaction. As soon as the event is triggered, you should fetch the charge and update the order status in your shop according to its status.

    Transaction status isResumed:true indicates, customer has successfully approved the order on PayPal payment page, and you can proceed on this transaction.

    GET /payments/s-pay-8538/charges/s-chg-1

Body:
{
}

    $unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$charge = $unzer->fetchChargeById($paymentId, $chargeId);

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Charge charge = unzer.fetchCharge(paymentId, chargeId);

    The response looks similar to the following example:

    {
    "id": "s-chg-1",
    "isSuccess": false,
    "isPending": true,
    "isResumed": true,
    "isError": false,
    "card3ds": false,
    "redirectUrl": "https://sbx-payment.unzer.com/v1/redirect/paypalot/s-jjlC9FrQrZ7q",
    "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": "195.9000",
    "currency": "EUR",
    "returnUrl": "https://unzer.com/",
    "date": "2022-10-31 12:59:07",
    "resources": {
        "customerId": "s-cst-0b5fbac8e1fb",
        "paymentId": "s-pay-8538",
        "basketId": "s-bsk-5e612a68be0b",
        "traceId": "e8664e249367acee81480e9ae4f74b1f",
        "typeId": "s-ppl-skki29gw2fue"
    },
    "additionalTransactionData": {
        "paypal": {
            "checkoutType": "express"
        }
    },
    "orderId": "YourOrderId1234",
    "paymentReference": "YourReference",
    "processing": {
        "uniqueId": "31HA07BC8137FFAF17A44DC072DB429E",
        "shortId": "5311.4754.5055",
        "traceId": "e8664e249367acee81480e9ae4f74b1f"
    }
}

    Fetch customer data

    Fetch the customer resource, which is now linked to the charges transaction. The customer resource is containing complete customer billing and shipping address data provided by PayPal.

    For a full description of customer resource, refer to the relevant server-side-integration documentation page: Manage customer.

    GET /customers/s-cst-0b5fbac8e1fb

Body:
{
}

    $unzer = new Unzer('s-priv-xxxxxxxxxx');
$unzer->fetchCustomer($customerId);

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Customer customer = unzer.fetchCustomer(customerId);

    The response looks similar to the following example:

    {
    "id": "s-cst-0b5fbac8e1fb",
    "lastname": "Doe",
    "firstname": "John",
    "salutation": "mr",
    "company": "",
    "customerId": "",
    "birthDate": "1987-12-20",
    "email": "John.Doe@unzer.com",
    "phone": "+4962216471100",
    "mobile": "",
    "language": "de",
    "billingAddress": {
        "name": "John Doe",
        "street": "Hugo-Junkers-Str. 5",
        "state": "DE",
        "zip": "60386",
        "city": "Frankfurt am Main",
        "country": "DE"
    },
    "shippingAddress": {
        "name": "John Doe",
        "street": "Hugo-Junkers-Str. 5",
        "state": "DE",
        "zip": "60386",
        "city": "Frankfurt am Main",
        "country": "DE",
        "shippingType": "equals-billing"
    },
    "geoLocation": {
        "clientIp": "87.163.144.231",
        "countryIsoA2": "DE"
    }
}

    (Optional) Recalculate the charge amount

    With customer’s address data you can now recalculate the charge amount, for example, if due to customer’s shipping address higher shipping costs are applied.

    Optional: Update the basket and the charge amount

    If you want to change the initial amount of your charges transaction, update the basket you’ve used in the POST /payments/charges request, display the updated basket and final charge amount to the customer. Ask the customer to finally confirm the changes.

    Refer to the Update a basket guide to learn more on how to update basket resources.

    Make a PATCH /payments/{paymentId}/charges

    Once the customer has finally confirmed the changed amount in your shop, make a PATCH on the initially created charge transaction to complete the PayPal Express transaction.

    Provide the updated charge amount in the PATCH /payments/{paymentId}/charges request. An updated basket doesn’t need to be provided again, the basketId includes the changes that you’ve applied. These will be considered automatically.

    With a successful PATCH /payments/{paymentId}/charges the payment status is set on completed now.

    icon
    If the basket and charge amount don’t need to be updated, just initialize a PATCH /payments/{paymentId}/charges with an empty body.
    PATCH /payments/s-pay-8538/charges/s-chg-1

Body:
{
    "amount": "210.90"
}

    $unzer = new Unzer('s-priv-xxxxxxxxxx');
$charge = new Charge(210.9);
$unzer->updateCharge($paymentId, $charge);

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Charge charge = unzer.fetchCharge(paymentId, chargeId);
charge.setAmount(BigDecimal.valueOf(210.9));
unzer.updateCharge(charge);

    The response looks similar to the following example:

    {
    "id": "s-chg-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "card3ds": false,
    "redirectUrl": "https://sbx-payment.unzer.com/v1/redirect/paypalot/s-jjlC9FrQrZ7q",
    "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": "210.9000",
    "currency": "EUR",
    "returnUrl": "https://unzer.com/",
    "date": "2022-10-31 12:59:07",
    "resources": {
        "customerId": "s-cst-0b5fbac8e1fb",
        "paymentId": "s-pay-8538",
        "basketId": "s-bsk-5e612a68be0b",
        "metadataId": "",
        "payPageId": "",
        "traceId": "e8664e249367acee81480e9ae4f74b1f",
        "typeId": "s-ppl-skki29gw2fue"
    },
    "additionalTransactionData": {
        "paypal": {
            "checkoutType": "express"
        }
    }
    "orderId": "YourOrderId1234",
    "paymentReference": "YourReference",
    "processing": {
        "uniqueId": "31HA07BC8137FFAF17A44DC072DB429E",
        "shortId": "5311.4754.5055",
        "paypalBuyerId": "JHQEVB7FYWUHW",
        "traceId": "e8664e249367acee81480e9ae4f74b1f"
    }
}

    Option 2: Make an authorize transaction

    Make a POST /payments/authorize

    Now, make an authorize transaction with the Paypal typeId and basketId that you created and the returnUrl leading back to your shop after the customer has successfully approved the order on the PayPal payment page. With authorize, the transaction is created, but the amount is not reserved yet in the wallet. Initially, the transaction is pending and a payment resource is created.

    POST /payments/authorize

Body:
{
    "amount": "195.90",
    "currency": "EUR",
    "returnUrl": "https://unzer.com/",
    "paymentReference": "Example Reference",
    "orderId": "ExampleOrderId1234",
    "resources": {
        "typeId": "s-ppl-twq0jsaafyny",
        "basketId": "s-bsk-12345"
    },
    "additionalTransactionData": {
        "paypal": {
            "checkoutType": "express"
        }
    }
}

    $unzer = new Unzer('s-priv-xxxxxxxxxx');
$authorize = (new Authorization(195.9, 'EUR', 'https://unzer.com/'))
    ->setCheckoutType('express', $paypal)
    ->setPaymentReference("Example Reference")
    ->setOrderId("ExampleOrderId1234");
    
$unzer->performAuthorization($authorize, $paypal, null, null, $basket);

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Authorization authorization = (Authorization) new Authorization()
    .setAmount(BigDecimal.valueOf(195.9))
    .setCurrencyCode(Currency.getInstance("EUR"))
    .setReturnUrl("https://unzer.com/")
    .setPaymentReference("Example Reference")
    .setOrderId("ExampleOrderId1234");
    .setAdditionalTransactionData(
      new AdditionalTransactionData()
        .setPaypal(new PaypalData().setCheckoutType(PaypalData.CheckoutType.EXPRESS))
    );
unzer.authorize(authorization);

    The response looks similar to the following example:

    {
    "id": "s-aut-1",
    "isSuccess": false,
    "isPending": true,
    "isError": false,
    "isResumed": false
    "redirectUrl": "https://sbx-payment.unzer.com/v1/redirect/paypal/s-ky7ZyEmKNjiC",
    "message": {
        "code": "COR.000.200.000",
        "merchant": "Transaction pending",
        "customer": "Your payment is currently pending. Please contact us for more information."
    },
    "amount": "195.9000",
    "currency": "EUR",
    "returnUrl": "https://unzer.com/",
    "date": "2022-10-31 12:48:12",
    "resources": {
        "customerId": "",
        "paymentId": "s-pay-8537",
        "basketId": "s-bsk-12345",
        "metadataId": "",
        "traceId": "f24acee84b5d28324489a7860bc7ffb2",
        "typeId": "s-ppl-skki29gw2fue"
    },
    "additionalTransactionData": {
        "paypal": {
            "checkoutType": "express"
        }
    },
    "orderId": "YourOrderId1234",
    "paymentReference": "Example Reference",
    "processing": {
        "uniqueId": "31HA07BC8137FFAF17A41E1EADC47133",
        "shortId": "5311.4688.9455",
        "traceId": "f24acee84b5d28324489a7860bc7ffb2"
    }
}

    Fetch the result of POST /payments/authorize

    We recommend subscribing to the authorize event to receive notifications about any changes to the authorize transaction. As soon as the event is triggered, you should fetch the authorize transaction and update the order status in your shop according to its status.

    Transaction status isResumed:true indicates, customer has successfully approved the order on PayPal payment page, and you can proceed on this transaction.

    GET /payments/s-pay-8538/authorize/s-aut-1

Body:
{
}

    $unzer = new Unzer('s-priv-xxxxxxxxxx');
$unzer->fetchAuthorization($paymentId);

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Charge charge = unzer.fetchAuthorization(paymentId);

    The response looks similar to the following example:

    {
    "id": "s-aut-1",
    "isSuccess": false,
    "isPending": true,
    "isResumed": true,
    "isError": false,
    "card3ds": false,
    "redirectUrl": "https://sbx-payment.unzer.com/v1/redirect/paypalot/s-jjlC9FrQrZ7q",
    "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": "195.9000",
    "currency": "EUR",
    "returnUrl": "https://unzer.com/",
    "date": "2022-10-31 12:59:07",
    "resources": {
        "customerId": "s-cst-0b5fbac8e1fb",
        "paymentId": "s-pay-8538",
        "basketId": "s-bsk-5e612a68be0b",
        "traceId": "e8664e249367acee81480e9ae4f74b1f",
        "typeId": "s-ppl-skki29gw2fue"
    },
    "additionalTransactionData": {
        "paypal": {
            "checkoutType": "express"
        }
    },
    "orderId": "YourOrderId1234",
    "paymentReference": "YourReference",
    "processing": {
        "uniqueId": "31HA07BC8137FFAF17A44DC072DB429E",
        "shortId": "5311.4754.5055",
        "traceId": "e8664e249367acee81480e9ae4f74b1f"
    }
}

    Fetch the customer data

    Fetch the customer resource, which is now linked to the charges transaction. The customer resource is containing complete customer billing and shipping address data provided by PayPal.

    For a full description of customer resource, refer to the relevant server-side-integration documentation page: Manage customer.

    GET /customers/s-cst-0b5fbac8e1fb

Body:
{
}

    $unzer = new Unzer('s-priv-xxxxxxxxxx');
$unzer->fetchCustomer($customerId);

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Customer customer = unzer.fetchCustomer(customerId);

    The response looks similar to the following example:

    {
    "id": "s-cst-0b5fbac8e1fb",
    "lastname": "Doe",
    "firstname": "John",
    "salutation": "mr",
    "company": "",
    "customerId": "",
    "birthDate": "1987-12-20",
    "email": "John.Doe@unzer.com",
    "phone": "+4962216471100",
    "mobile": "",
    "language": "de",
    "billingAddress": {
        "name": "John Doe",
        "street": "Hugo-Junkers-Str. 5",
        "state": "DE",
        "zip": "60386",
        "city": "Frankfurt am Main",
        "country": "DE"
    },
    "shippingAddress": {
        "name": "John Doe",
        "street": "Hugo-Junkers-Str. 5",
        "state": "DE",
        "zip": "60386",
        "city": "Frankfurt am Main",
        "country": "DE",
        "shippingType": "equals-billing"
    },
    "geoLocation": {
        "clientIp": "87.163.144.231",
        "countryIsoA2": "DE"
    }
}

    (Optional) Recalculate the authorize amount

    With customer’s address data you can now recalculate the authorize amount, for example, if due to customer’s shipping address higher shipping costs are applied.

    Optional: Update basket and authorize amount

    If you want to change the initial amount of your authorize transaction, update the basket you’ve used in the POST /payments/authorize request, display the updated basket and final authorize amount to the customer. Ask the customer to finally confirm the changes.

    Refer to the Update a basket guide to learn more on how to update basket resources.

    Make a PATCH /payments/{paymentId}/authorize

    Once the customer has finally confirmed the changed amount in your shop, make a PATCH on the initially created authorize transaction to complete the PayPal Express transaction.

    Provide the updated authorize amount in the PATCH /payments/{paymentId}/authorize request. An updated basket don’t need to be provided again, the basketId incl changes you’ve applied will be considered automatically.

    With a successful PATCH /payments/{paymentId}/authorize the transaction status is set on success now - the payment status remains on pending as long as no charge has been initialized.

    icon
    If the basket and charge amount are not required to be updated, just initialize a PATCH /payments/{paymentId}/charges with an empty body.
    PATCH /payments/s-pay-8538/authorize

Body:
{
    "amount": "210.90"
}

    $unzer = new Unzer('s-priv-xxxxxxxxxx');
$authorize = new Authorization(210.9);
$unzer->updateAuthorization($paymentId, $authorize);

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Authorization authorization = unzer.fetchAuthorization(paymentId);
authorization.setAmount(BigDecimal.valueOf(210.9));
unzer.updateAuthorization(authorization);

    The response looks similar to the following example:

    {
    "id": "s-aut-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "card3ds": false,
    "redirectUrl": "https://sbx-payment.unzer.com/v1/redirect/paypalot/s-jjlC9FrQrZ7q",
    "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": "210.9000",
    "currency": "EUR",
    "returnUrl": "https://unzer.com/",
    "date": "2022-10-31 12:59:07",
    "resources": {
        "customerId": "s-cst-0b5fbac8e1fb",
        "paymentId": "s-pay-8538",
        "basketId": "s-bsk-5e612a68be0b",
        "metadataId": "",
        "payPageId": "",
        "traceId": "e8664e249367acee81480e9ae4f74b1f",
        "typeId": "s-ppl-skki29gw2fue"
    },
    "additionalTransactionData": {
        "paypal": {
            "checkoutType": "express"
        }
    }
    "orderId": "YourOrderId1234",
    "paymentReference": "YourReference",
    "processing": {
        "uniqueId": "31HA07BC8137FFAF17A44DC072DB429E",
        "shortId": "5311.4754.5055",
        "paypalBuyerId": "JHQEVB7FYWUHW",
        "traceId": "e8664e249367acee81480e9ae4f74b1f"
    }
}

    For a full description of the authorize transaction, see the relevant server-side-integration documentation page: Authorize a payment (direct API calls), Authorize a payment (PHP SDK), Authorize a payment (Java SDK).

    Charge the authorization

    Because the customer already accepted the order with the authorize transaction, you can now charge the payment to transfer the money.

    When you authorize before charge, the authorized amount is on hold for 29 days. Paypal however, recommends to charge the funds within the three-day honor period. The success of the charge is subject to risk and availability of funds on the authorized payment instrument.

    POST https://api.unzer.com/v1/payments/s-pay-1/charges
   
{
  "amount": 20,
  "paymentReference": "Test charge transaction"
}

    $unzer = new Unzer('s-priv-xxxxxxxxx');
$charge = $unzer->performChargeOnPayment('s-pay-1', new Charge());

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Charge charge = unzer.chargeAuthorization("s-pay-1");

    The response looks similar to the following example:

    {
    "id": "s-chg-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "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": "20.0000",
    "currency": "EUR",
    "date": "2021-06-04 15:33:16",
    "resources": {
        "customerId": "s-cst-d6ae94482612",
        "paymentId": "s-pay-1",
        "basketId": "",
        "metadataId": "",
        "payPageId": "",
        "traceId": "4ebfbfcae640ff2823e2e65febd54037",
        "typeId": "s-ppl-4x3zn7i4bxyh"
    },
    "paymentReference": "Test charge transaction",
    "processing": {
        "uniqueId": "31HA07BC8198C2F9107E38AF14C45201",
        "shortId": "4867.4719.2103",
        "traceId": "4ebfbfcae640ff2823e2e65febd54037"
    }
}

    Step 4: Check status of the payment
    server side

    Once the customer is redirected to the returnUrl, you can fetch the payment details from the API, by using the resources.paymentId from the charge response above to handle the payment according to its status. If the status of the payment is completed, the payment process has been finished successfully and can be considered as paid. Check all possible payment states here.

    GET https://api.unzer.com/v1/payments/{payment_ID}

{
    "id": "s-pay-131937",
    "state": {
        "id": 1,
        "name": "completed"
    },
    "amount": {
        "total": "20.0000",
        "charged": "20.0000",
        "canceled": "0.0000",
        "remaining": "0.0000"
    },
    "currency": "EUR",
    "orderId": "",
    "invoiceId": "",
    "resources": {
        "customerId": "",
        "paymentId": "s-pay-131937",
        "basketId": "",
        "metadataId": "",
        "payPageId": "",
        "traceId": "70ddf3152a798c554d9751a6d77812ae",
        "typeId": "s-ppl-grpucjmy5zrk"
    },
    "transactions": [
        {
            "date": "2021-05-10 00:51:03",
            "type": "charge",
            "status": "success",
            "url": "https://api.unzer.com/v1/payments/s-pay-131937/charges/s-chg-1",
            "amount": "20.0000"
        }
    ]
}

    Step 5: Display the payment result
    client side

    Use the information from the Check status of the payment step to show payment result to your customer.
    This can be the success or error page of your shop. If something went wrong you can use the client message from the API response and show it to the customer.

    Manage payment
    server side

    For more details on managing PayPal payments, such as refunding them, see Manage PayPal payments

    Notifications

    We recommend subscribing to the payment event to receive notifications about any changes to the payment resource. As soon as the event is triggered you should fetch the payment and update the order status in your shop according to its status.

      {
    "event":"payment.pending",
    "publicKey":"s-pub-xxxxxxxxxx",
    "retrieveUrl":"https://api.unzer.com/v1/payments/s-pay-774",
    "paymentId":"s-pay-774"
  }

    For more details on implementing webhooks to receive notifications, see Notifications page.

    Error handling

    All requests to the API can result in an error that should be handled. Refer to the Error handling guide to learn more about Unzer API (and other) errors and handling them.

    Test & go live

    You should always test your integration before going live. First perform test transactions using test data. Next, check against Integration checklist and Go-live checklist to make sure the integration is complete and you’re ready to go live.

    See also