PayPal Recurring (Billing agreement)
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
Response parameter | Description |
---|---|
approval_code | Transaction approval code. Initial character indicates the transaction status. ‘Y’ – Transaction approved ‘N’ – Transaction declined ‘?:waiting PAYPAL’ – Transaction has been initiated but a final result is not yet available |
status | Transaction status, e.g. ‘APPROVED’, ‘DECLINED’, ‘FAILED’ or ‘WAITING’ |
hostedDataId | Stores “Billing Agreement ID” |
sname | Ship-to Name |
saddr1 | Shipping Address |
scity | Shipping City |
scountry | Country of Shipping Address |
szip | Zip or Postal Code |
fail_reason | Indicates why the transaction was declined |
ipgTransactionId | It is mapped to the PayPal Custom. You will be able to see this value in your PayPal seller account while reviewing a transaction |
refnumber | Represents the PayPal Transaction ID. The value will be visible in your PayPal seller account while reviewing a transaction |
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
Updated about 2 months ago