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, which makes merchant integration much easier and quicker.

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. We recommend using the Java SDK, mobile SDK for iOS or mobile SDK for Android.
  • 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 new type

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.

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. We recommend using the Java SDK, mobile SDK for iOS or mobile SDK for Android.
  • 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 the use of a personal PayPal developer account is possible.