PayPal

Last changes: 07-06-2020

1. Initiate Storing of New Payment Option

The storing of a new payment option is initialized by calling the API method 1.53 Init Add Stored Payment Option.

In the example below, we initiate the storing of a PayPal payment option for the account number KDNR0001.

Initiate Storing of New Payment Option Request

Path:

POST {Base URL}/account/KDNR0001/storedPaymentOptions/initAdd

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: H4sIAAAAAAA{partial omission for brevity}EAN2bJ/6l2XX+A5kJqdP+MwAA

{
    "partnerReference": "DEV-SVR001-DE_CUSTID-FT7QPP3PDB_CARTID-G8H8R8RFBR_KGBPK839DQ",
    "programCode": "COMPANYDE",
    "accnoType": "00",
    "paymentOptionCode": "PAYPAL",
    "localDate": "2018-11-11",
    "localTime": "013356",
    "criteria": [
        {
            "name": "returnURL",
            "value": "https://example.com/StoredPaymentOptions/CompleteAdd"
        },
        {
            "name": "cancelURL",
            "value": "https://example.com/StoredPaymentOptions/CancelAdd"
        }
    ]
}

The “returnUrl” and “cancelUrl” (in the “criteria”-object) specify, where the customer is redirected after a successful or failed storing, respectively.

Initiate Storing of New Payment Option Response

Status Code:

201 (Created)

Header:

Content-Type: application/json
Accept-Language: en-US

{
    "accno": "KDNR0001",
    "authorizationToken": "BA-59M8127852558605H",
    "paymentOptionCode": "PAYPAL",
    "paymentProviderResponse": {
        "links": [
            {
                "href": "https://.../approve?ba_token=BA-59M8127852558605H",
                "rel": "approval_url",
                "method": "POST"
            },
            {
                "href": "https://.../billing-agreements/BA-59M8127852558605H/agreements",
                "rel": "self",
                "method": "POST"
            }
        ],
        "token_id": "BA-59M8127852558605H"
    },
    "programCode": "COMPANYDE",
    "partnerReference": "DEV-SVR001-DE_CUSTID-YHHG97XPCD_CARTID-BJ4PB47WWW_72Y9YWDG7V",
    "localDate": "2018-11-11",
    "localTime": "012844",
    "sysDate": "2018-11-11",
    "sysTime": "002846",
    "responseCode": "0000",
    "responseDescription": "Successful execution"
}

The response includes the desired authorization token under the return parameter "authorizationToken" which is needed to complete the storing of the payment option in further steps.

2. Collect Payment Option Details via SDK

The SDK renders a customizable PayPal button and transmits all necessary payment details to start the PayPal flow. We offer SDKs for the integration into websites as well as mobile applications (Android and iOS).

 

The Web SDK is used to securely collect the payment option details. The authorization token returned by the API method 1.53 Init Add Stored Payment Option which initiated the storing is used to associate the payment option details collected via the Web SDK with the storing process.

Collect Payment Option Details via Web SDK

// Initialize Payment Form renderer options.
cw.initialize({
    enablePayPal: true // Required for PayPal provider.
});

// Configure and render the Payment Form
cw.PaymentForm(container,
{
    authorizationToken: "BA-59M8127852558605H",
    paymentOptionCodes: ["PAYPAL"],
    paymentProviderMode: "test",
    paypalButtonStyle: {   // optional
    size: "medium",    // default "small"
    color: "blue",     // default "gold"
    shape: "rect",     // default "pill"
    label: "paypal",   // default "paypal"
    tagline: "false"   // default "false"
}
});

A detailed guide how to customize the PayPal button is provided on the PayPal Developer Portal.

After the shopper submits the payment form by clicking the button labeled with the value of "submitButtonTitle" (see example above), he is redirected to the "returnUrl" specified in section 1. Initiate Storing of New Payment Option.

 

3. PayPal Login

PayPal displays a login page, but keeps the customer local to your website or mobile app throughout the payment process.

The customer can either directly enter their login credentials or create a new PayPal account. In the latter case, they must specify a new payment option (e.g. credit card or bank account).

4. Billing Agreement

Following this, the Welcome back page shows a billing agreement. Clicking the accept-button, the customer authorizes you to debit the chosen payment option via the PayPal-account.

After confirming the billing agreement, the shopper is redirected to the “returnUrl”, which you previously specified in 1. Initiate Storing of New Payment Option.

5. Complete Storing of New Payment Option

Since the SDK sends the payment option details directly to PayPal, you have no knowledge about its current status and if it got authorized. Therefore, call the API method 1.54 Complete Add Store Payment Option from your server-side method behind the “returnUrl”.

Complete Storing of New Payment Option Request

Path:

PUT {Base URL}/account/KDNR0001/storedPaymentOptions/completeAdd

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: H4sIAAAAAAA{partial omission for brevity}EAN2bJ/6l2XX+A5kJqdP+MwAA

{
    "partnerReference": "DEV-SVR001-DE_CUSTID-YHHG97XPCD_CARTID-BJ4PB47WWW_72Y9YWDG7V",
    "programCode": "COMPANYDE",
    "accnoType": "00",
    "paymentOptionCode": "PAYPAL",
    "authorizationToken": "BA-59M8127852558605H",
    "useDifferentBillingAddress": true,
    "customerFullName": "Jacob Smith",
    "addr1": "Anystreet",
    "houseNumber": "321",
    "city": "Anycity",
    "countryCode": "DE",
    "postCode": "12345",
    "localDate": "2018-11-11",
    "localTime": "013140",
}

Complete Storing of New Payment Option Response

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
    "accno": "KDNR0001",
    "paymentOptionCode": "PAYPAL",
    "storedPaymentOptionReference": "BA-59M8127852558605H",
    "initiationCountryCode": "DE",
    "initiationCountryCode3": "DEU",
    "paymentProviderResponse": {
        "id": "BA-59M8127852558605H",
        "state": "ACTIVE",
        "description": "Billing Agreement with Volkswagen Payments S.A. (SANDBOX) on behalf of Umbrella Europe direct",
        "payer": {
            "payer_info": {
                "email": "j.smith999@example.com",
                "first_name": "Jacob",
                "last_name": "Smith",
                "payer_id": "FJFBNSGR8YTBC"
            }
        },
        "plan": {
            "type": "MERCHANT_INITIATED_BILLING",
            "merchant_preferences": {
                "accepted_pymt_type": "INSTANT"
            }
        },
        "links": [
            {
                "href": "https://.../agreements/B-7XV75224PH649735W/cancel",
                "rel": "cancel",
                "method": "POST"
            },
            {
                "href": "https://.../agreements/B-7XV75224PH649735W",
                "rel": "self",
                "method": "GET"
            }
        ],
        "merchant": {
            "payee_info": {
                "email": "APMvwfsLux-facilitator@vwfs.com"
            }
        },
        "create_time": "2018-11-11T00:31:40Z",
        "update_time": "2018-11-11T00:31:40Z"
    },
    "programCode": "COMPANYDE",
    "partnerReference": "DEV-SVR001-DE_CUSTID-YHHG97XPCD_CARTID-BJ4PB47WWW_72Y9YWDG7V",
    "localDate": "2018-11-11",
    "localTime": "013140",
    "localDate": "2018-11-11",
    "localTime": "003140",
    "responseCode": "0000",
    "responseDescription": "Successful execution"
}

The "responseCode" 0000 and the “responseDescription” indicate that the new payment option has been successfully stored.

The storedPaymentOptionReference" parameter is used to identify the tokenized payment option as part of other API methods (see section Payment Process). You can either store it on your server or retrieve it via an API call (see section Get Stored Payment Options).