alt

Important information

There was an update of Unzer TLS/SSL certificates. Learn more

Unzer

Accept PayPal Express with server-side-only integration

Build your own payment form to add PayPal Express payment to the checkout page.

Overview

The PayPal Express payment method doesn’t require any input from the customer, such as shipping or billing address or an account creation on your website. When the customer selects Paypal express as a payment method, their address information is received via Unzer from the PayPal wallet and can be used for the checkout.

Before you begin

  • Contact Unzer to activate your merchant account for PayPal Express usage.

Step 1: Create a payment type resource
server side

When creating the payment type PayPal, you need to send a request to the Unzer API. The response contains an id, this is later referred to as typeId. You will need this typeId to perform the transaction. The customer email is an optional field.

POST https://api.unzer.com/v1/types/paypal/

Body:
{
}
$unzer = new Unzer('s-priv-xxxxxxxxxx');

$paypal = new Paypal();
$paypal = $unzer->createPaymentType($paypal);
Paypal paypal = new Paypal();
Unzer unzer = new Unzer(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
paypal = unzer.createPaymentType(paypal);

The response looks similar to the following example:

{
  "id": "s-ppl-skki29gw2fue",
  "method": "paypal",
  "recurring": false,
  "geoLocation": {
    "clientIp": "127.0.0.1",
    "countryCode": "DE"
  }
}

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, as well as 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"
    }
  ]
}
(see basket example UPL Invoice)
e.g.
$unzer= new Unzer('s-priv-xxxxxxxxxx');
$basketItem = (new UnzerSDK\Resources\EmbeddedResources\BasketItem())
  ->setTitle('Notebook pro')
  ->setSubTitle('basket item subtitle')
  ->setBasketItemReferenceId('item-1')
  ->setQuantity(1)
  ->setTotalValueGross(2000)
  ->setVat(19.0)
  ->setType(UnzerSDK\Constants\BasketItemTypes::GOODS)
  ->setUnit('pc');

$basket  = (new UnzerSDK\Resources\Basket())
  ->setTotalValueGross(2000)
  ->setCurrencyCode('EUR')
  ->setOrderId('O-12345-AB')
  ->setNode('basket note')
  ->addBasketItem($basketItem);

$unzer->createBasket($basket);
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx")
BasketItem basketItem = new BasketItem()
  .setTitle("Notebook pro")
  .setSubtitle("basket item subtitle")
  .setBasketItemReferenceId("item-1")
  .setQuantity(1)
  .setTotalValueGross(BigDecimal.valueOf(2000))
  .setVat(BigDecimal.valueOf(19.))
  .setType(Type.GOODS)
  .setUnit("pc");
  
Basket basket = new Basket()
  .setTotalValueGross(BigDecimal.valueOf(2000.))
  .setCurrencyCode(Currency.getInstance("EUR"))
  .addBasketItem(basketItem);
  
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": ""
    },
    "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/{chargesId}

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/{chargesId} 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/{chargesId} 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/{chargesId} 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": ""
    },
    "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/{authorizesId}

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/{authorizeId} 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/{authorizeId} 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/{chargesId} with an empty body.
PATCH /payments/s-pay-8538/authorize/s-aut-1

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/{resource_ID}>/charges/{transaction_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