PayPal

PayPal Holdings, Inc. is an American company operating a worldwide online payments system that supports online money transfers and serves as an electronic alternative to traditional paper methods like cheques and money orders.

More than 244 million customers are using PayPal. By using PayPal more than 25 currencies are available.

The customer has to sign up for a PayPal account. Afterwards there is no need to enter the payment details again during the payment process.

Recently PayPal has introduced PayPal Express Checkout for a faster checkout experience. The customer does not need to enter their address details when they are paying on your website. Refer to PayPal Express for more details.

Authorize or Charge
Paypal offers two options:
* Authorize (Reserve) and Charge
* Direct Charge

PayPal - direct charge

beaea20-paypal-direct-charge.png

Executing a Paypal transaction is a three-step process:

  • Step1: Create a new /types/paypal resource using the JavaScript SDK.
  • Step 2: Execute a /payments/charges call with the reference to the types resource.
  • Step 3: Forward customer to redirectUrl provided within charge response.

Step 1 - Create a paypal resource

Create the payment type resource. For PayPal Express, the Content-Type is application/com.unzer.api.types.paypal.v2+json in the Headers parameter.

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

Body:
{
    "amount": "100",
    "currency": "USD",
    "basketId":"s-bsk-123",
    "customerId":"s-cst-123",
    "email": "vhkhang91@gmail.com"
}
// heidelpayUI
var Unzer = new Unzer('s-pub-xxx');

// Paypal
var Paypal = heidelpayInstance.Paypal()

// Create resource
Paypal.createResource()
  .then(function (data) {
    console.log("Paypal Resource: ", data)
    })
// sampe successful response

{
  "id": "s-ppl-skki29gw2fue",
  "method": "paypal",
  "recurring": false,
  "geoLocation": {
    "clientIp": "115.77.189.143",
    "countryCode": "VN"
  },
  "email": "t*****1@n******a"
}

By using the request, a resource is created and the resource id (e.g. s-ppl-23ashaor54) is returned.

PayPal Express
For PayPal Express, you will get the customer details when the PayPal flow is completed successfully. You must create Paypal Express button callbacks or webhook notifications to get the customer details.
Parameter Mandatory
amount Yes (if PayPal Express)
currency Yes (if PayPal Express)
basketId Optional (if PayPal Express)
customerId Optional (if PayPal Express)
email Optional

Step 2 - Charge a payment

After creating the types resource, it is possible to create a *charge *request. If you want to use “PayPal buyer protection” you need to create a customer with a shipping address.

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

Body:
{
       "amount":       "12.4500",                                    
       "currency":     "EUR",
       "returnUrl":    "https://www.unzer.com",
       "resources": {
           "typeId":        "s-ppl-23ashaor54"
       }
}

The result will be a pending charge with a redirectUrl.

// UnzerAPI - response example

{
    "id":               "s-chg-1",
    "isSuccess":        false,
    "isPending":        true,
    "isError":          false,
    "redirectUrl":      "https://payment.unzer.com/paypal/3849234023942354935353405234320423",
    ...
}

Step 3 - Redirect customer to redirectUrl

You must send the customer to the redirectUrl, where they are redirected to the PayPal payment page. After successful payment or cancellation, the customer will be redirected to the returnURL that you specified in the charge call.

After the customer has been redirected to returnUrl, you should check the status of the payment by getting the payment ID.

// UnzerAPI - fetch final result

GET https://api.unzer.com/v1/payments/<id>/charges/<id>

{
    "id":                "s-chg-1",
    "isSuccess":   true,
    "isPending":   false,
    "isError":     false,
    "redirectUrl": "",
     ...
}

Authorize and charge

PayPal also supports the authorization of a payment and its subsequent processing. So you can reserve money on the PayPal account and charge this amount later.

70a75f8-paypal-authorize-charge.png

Authorize a payment is a three-step process:

  • Step1: Create a new resource /types/paypal using the JavaScript SDK.
  • Step 2: Execute a /payments/authorize call with the reference to the types resource.
  • Step 3: Forward customer to redirectUrl provided within charge response.

Charge after authorize can be done later using the /payments/{paymentId}/charges call. You can execute the call without any parameter. In this case the full authorization amount will be charged. You can also provide an amount. In this case only the provided amount will be charged. You can later charge the rest of the amount.

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

{
  "amount" : "50"
}

Sandbox test data

For testing the integration, do not use real customer data. Use the test data prepared by Unzer.

Additionally, you can also use your PayPal developer account.