Initial setup of a billing agreement via Hosted Payment Page

📘

Pre-conditions

On the gateway side, your account must be set up with the Data Vault / Hosted Data service.

Please contact PayPal to verify if your PayPal business account meets the PayPal requirements for this feature.

Besides sending the paymentMethod as 'paypal', you need to submit the parameter chargetotal with a zero value in your preauthorization request. Such transaction request is always used to create a Billing Agreement ID on the PayPal side, returned to you in the field hostedDataId

Transaction Response

Recurring Payment (based on PayPal Billing Agreement) via REST PAYMENTS API

requestType can be either "ApmSaleTransaction" or "ApmPreAuthTransaction".

After creation of the billing agreement, you can conduct a subsequent payment by constructing a so called merchant-initiated transaction (in this case recurring transaction) and submit it via the RESTful payment API (or via any other submission component such as Connect ). While doing so, you will have to include the hosted data ID (=token returned in the initial response) into paymentToken and set the value paymentMethod set to ‘PAYPAL'.

Endpoint: POST | .../ipgrestapi/v2/services/payments

Example:

{
    "requestType": "ApmSaleTransaction",
    "transactionAmount": {
        "total": "10.00",
        "currency": "EUR"
    },
    "transactionOrigin": "ECOM",
    "paymentMethod": {
        "type": "PAYPAL",
        "paymentToken": "JohnTestToken" // this is the token created via hosted payment page
    }
}

{
    "clientRequestId": "d5e65c95-b564-4ae1-a694-772f4d51754b",
    "apiTraceId": "ZWdDR30AIUWWHD8ij96dSQAAA24",
    "ipgTransactionId": "84454986171",
    "orderId": "R-899513e7-5f3e-4f40-81f6-0c3a0a9e43b8",
    "paymentToken": {
        "value": "JohnTestToken",
        "reusable": true,
        "declineDuplicates": false
    },
    "transactionTime": 1701266247,
    "approvedAmount": {
        "total": 10,
        "currency": "EUR",
        "components": {}
    },
    "transactionAmount": {
        "total": 10,
        "currency": "EUR",
        "components": {}
    },
    "transactionStatus": "APPROVED",
    "approvalCode": "Y:000000:4454986171:PP X:30N172696W940135K",
    "processor": {
        "referenceNumber": "30N172696W940135K",
        "responseCode": "200",
        "responseMessage": "SUCCESS"
    }
} 

The Transaction will immediately be in a approved or failed state.

Cancel a Billing Agreement via REST PAYMENTS API

A Billing Agreement can be canceled by sending a void request for the PreAuth Transaction where the agreement was created. (Created via Hosted Payment Page)

Endpoint: POST | .../ipgrestapi/v2/services/payments/apm/

Example:

{

    "requestType": "VoidTransaction"

}

TO BE ADDED