PayPal payments
Last updated: 12-Nov-2024
Overview
Checkout can be used to accept PayPal payments.
This guide requires familiarity with Accepting payments.
PayPal processing fields
- customer - ID of a Customer created via the Customer API. A customer object can be created and attached to a Checkout. The customer object can store relevant customer details. Read all of the customer requirements needed for PayPal transactions.
- line_items - Shopping cart line items to be displayed on the page and sent to PayPal
- configurations.paypal - Object carrying the parameters required for making an Google Pay payment (Required)
- payment_contract_id - This ID can be found in the portal or given to you by a Verifone employee. It is used to retrieve merchant's PayPal credentials necessary for a payment. (Required)
- dynamic_descriptor - Short text to be displayed on the bank statement of the cardholder. Support varies per Payment Contract.
- capture_now - Used for separate authorization and capture
- invoice_number - PayPal invoice number
- application_context - Additional merchant options to control the appearance of PayPal's landing page
- description - Description of the payment shown to the shopper on the PayPal screen
Authorization and capture
PayPal transactions through the Checkout can be used to do a sale (capture_now = true) or to authorize without capturing immediately (capture_now = false). An authorized payment reserves the money and allows you to capture the funds at a later stage.
Handling responses
Whenever a card payment is processed via the Checkout, the responses events would contain additional fields specific to card payments in the details object.
Example of successful checkout via the Checkout:
[
{
"type": "TRANSACTION_INITIATED",
"id": "b5b5fa07-3c99-4613-92f7-e24c258b3269",
"timestamp": "2021-03-31T11:43:46.697Z",
"details": {
"id": "fd31890c-8c45-4846-a934-a7faa584e823",
"orderId": "71110696K0011224V",
"createdAt": "2021-03-31T11:43:45Z",
"status": "INITIATED",
"approvalUrl": "https://www.sandbox.paypal.com/checkoutnow?token=71110696K0011224V"
}
},
{
"type": "TRANSACTION_SUCCESS",
"id": "1aaebd63-2daf-4753-bc32-bcdb8c35b743",
"timestamp": "2021-03-31T11:44:07.717Z",
"details": {
"id": "fd31890c-8c45-4846-a934-a7faa584e823",
"captureId": "93459848W31137123",
"createdAt": "2021-03-31T11:44:06Z",
"isFinalCapture": true,
"payer": {
"payerId": "92FT3NN28KELQ",
"shippingAddress": {
"country": "IN",
"postalCode": "100047",
"countrySubdivision": "Maharashtra",
"city": "Mumbai",
"addressLine1": "addressLine1",
"addressLine2": "addressLine2",
}
},
"status": "AUTHORISED"
}
}
]Example of failed PayPal payment via the Checkout:
[
{
"type": "TRANSACTION_FAILED",
"id": "f2041250-4fc2-4b3a-bc94-651ba099541a",
"timestamp": "2020-07-08T12:42:37.974Z",
"details": {
"id": "6d85d047-1e78-4f13-afe2-cc041bce524f",
"authorizationId": "4PB16132MH590854B",
"createdAt": "2021-01-06T04:40:30Z",
"expiresAt": "2021-02-04T04:40:30Z",
"status": "FAILED",
"payer": {
"payerId": "92FT3NN28KELQ",
"shippingAddress": {
"country": "IN",
"postalCode": "100047",
"countrySubdivision": "Maharashtra",
"city": "Mumbai",
"addressLine1": "addressLine1",
"addressLine2": "addressLine2",
}
}
}
}
]To ensure that the redirection request was not tampered with, always check that the transaction_id received as query parameter in the redirection matches the transaction_id property of the retrieved Checkout. If those are not matching, this is indication of either an incorrect integration, that the redirection to your return_url did not originate from Verifone, or transaction_id was tampered with.
You can now store the transaction_id value together with the order 1234 in your system to link the two together.
Scenarios
The table below describes the different outcomes of a Checkout. A full list error codes are available.
| Description | Result | Merchant action |
|---|---|---|
| Failed transaction* | Redirect: checkout_id={checkout_id} & transaction_id={transaction_id} & errorCode=123 | Unsuccessful payment (technical reason), do not display order confirmation |
| Successful transaction | Redirect: checkout_id={checkout_id} & transaction_id={transaction_id} | Display order confirmation |
| Customer visits the URL of an already completed Checkout | Redirect: checkout_id={checkout_id} & errorCode=168 | Display corresponding message to customer. Checkout is completed whenever there was a single successful payment processed through it. |
| Customer visits the URL of an expired Checkout | Redirect: checkout_id={checkout_id} & errorCode=169 | Display corresponding message to customer. Checkout is expired whenever the expiry_time is reached. |
| Customer visits the URL of a Checkout which has reached the maximum of failed payment attempts | Redirect: checkout_id={checkout_id} & errorCode=165 | Display corresponding message to customer. Payments through a single Checkout can be attempted up to three times unsuccessfully. |
| Form validation errors / Other service failures on the Checkout page | Displays error alert to Customer on the page | Customer is prompted to correct their form input and retry the payment or try using alternate card or payment method |
*** Failed transaction - Depending on which step in the payment process failed, the transaction_id might not always be present as the query parameter
Rate this article:
