Guides

PayPal

Suggest Edits

Introduction to PayPal

PayPal is a globally recognized online payment platform that enables users to shop online and in person, make payments, send and receive money. Users can link their PayPal account to multiple funding sources including credit card, debit card, or bank account enabling fast and flexible payments.

PayPal via BR-DGE

PayPal as a Payment Processor offers a range of features including multiple payment instruments including card payments, "PayPal" payment instrument as well as Buy Now Pay Later (BNPL) features.

BR-DGE currently support the following features with PayPal:

📘

The BR-DGE PayPal integration covers the PayPal wallet payment instrument only.

Onboarding for PayPal

When integrating PayPal via the BR-DGE platform, you are enabling BR-DGE to act as a PayPal partner and manage API requests on your behalf. To enable PayPal on your BR-DGE retail channels, please get in contact with support..

Integration Methods

API

Integrate with the BR-DGE API to create PayPal Order and Payments via the BR-DGE endpoints

  • Step 1 - Initiate Checkout
    Your customer proceeds to your checkout page.
  • Step 2 - Select Payment Method
    Your customer picks PayPal as payment method.
  • Step 3 - Backend Communication
    Your checkout page communicates with your server side system.
  • Step 4 - Create PayPal Order via BR-DGE
    Your server side system creates a PayPal order with BR-DGE.
  • Step 5 - Receive Order response
    You will receive a BR-DGE PayPal order response.
  • Step 6 - Redirect Customer to PayPal
    Redirect your customer to the URL provided in the response in step 5 in order for them to approve the PayPal order.
  • Step 7 - Customer Approves Payment
    Your customer logs in to their PayPal account and approves the PayPal order.
  • Step 8 - PayPal Order Approval Confirmation
    You will be informed of the payment being approved when PayPal trigger the onApprove() method.
  • Step 9 - Capture or Authorize PayPal Order
    You call BR-DGE to authorize or capture the PayPal Order approved in Step 8.
  • Step 10 - Receive Payment Outcome
    BR-DGE would return a response with the outcome of the payment of the order.

📘

Where the intent of the payment is authorize, you will need to ensure you capture the payment at a later stage.

  • Step 11 - Redirect to Landing Page
    You will redirect your customer to the appropriate landing page depending on the outcome of the payment.

Create a PayPal Order

To create a PayPal order, send a request to /v1/paypal/orders with its mandatory fields.

📘

If you need to provide additional data for risk analysis you should include the optional customer and ota objects in your API request


{  
  "amount": 1000,  
  "currency": "GBP",  
  "displayName": "Brand Name",  
  "intent": "capture",  
  "customerOrderCode": "ABC123",  
  "locale": "en-GB",  
  "invoiceId": "987654321",  
  "enableShippingAddress": true,  
  "shippingAddressEditable": false,  
  "shippingAddressOverride": {  
    "address": "Line 2",  
    "town": "Edinburgh",  
    "county": "State",  
    "postcode": "EH10 8BT",  
    "country": "GB",  
    "phoneNumber": "001122334455",  
    "recipientName": "John Smith",  
    "buildingNumberOrName": "20"  
  },  
  "lineItems": [  
    {  
      "name": "Bus Ticket",  
      "description": "Bus Ticket to Destination",  
      "quantity": 1,  
      "unitAmount": 1000,  
      "unitTax": 100  
    }  
  ],  
  "customer": {  
    "accountId": "A12345N343",  
    "firstName": "John",  
    "lastName": "Smith",  
    "email": "[email protected]",  
    "phoneNumber": "(042) 1123 4567",  
    "country": "GB",  
    "creationTimestamp": "2012-12-09T19:14:55-277-0:00"  
  },  
  "ota": {  
    "type": "bus",  
    "serviceStartDate": "2012-12-09T19:14:55.277-0:00",  
    "serviceEndDate": "2012-12-09T19:14:55-277-0:00",  
    "changeGuest": false,  
    "startCountry": "US",  
    "startCity": "San Jose",  
    "startZipcode": "95131"  
  }  
}

You should expect to receive a response similar to the following

{  
  "id": "6839c22206f97cc880001902830cb141",  
  "code": "1000",  
  "message": "Order Created",  
  "orderId": "50190127TN3647157",  
  "redirectUrl": "https://www.sandbox.paypal.com/checkoutnow?token=50190127TN3647157",  
  "intent": "authorize",  
  "status": "CREATED",  
  "creationTimestamp": "2024-05-07T18:46:54Z"  
}

The link returned in the redirectUrl field should be used to redirect the payer to complete payer approval.

Payment Approval

Once your customer has approved the payment, PayPal will trigger the onApprove() event which you will listen for. Once PayPal have triggered this event you should send a POST request, from your server, to the BR-DGE API endpoint /v1/paypal/orders/{orderId}/payments to handle the payment authorisation, or capture.

Authorizing or Capturing an Order

Once created, a PayPal Order can be captured immediately, or authorised to be captured in the future.

Authorizing an order

To authorize a PayPal Order, send a request to /v1/paypal/orders/{orderId}/payment with an intent of authorize.

{  
  "intent": "authorize"  
}

You should expect to receive a response similar to the following

{
    "code": "1000",
    "message": "Approved",
    "id": "6846f914ee7a4aeb312482c2eb71ebc3",
    "paymentId": "630dd55a-6be5-4b83-a496-c6aedb2748a7",
    "orderId": "00M90400P30637624",
    "status": "CREATED",
    "amount": 1000
}

Immediate Capture

To capture a PayPal Order immediately send a request to /v1/paypal/orders/{orderId}/payment with an intent of capture.

{  
  "intent": "capture"  
}

You should expect to receive a response similar to the following

{  
  "code": "1000",  
  "message": "Approved",  
  "id": "6839c22206f97cc880001902830cb141",  
  "paymentId": "fcef7126-0620-4504-0846-14885f7aaf32",  
  "orderId": "22F56186004488027",  
  "status": "COMPLETED",  
  "amount": 1000  
}

Delayed Capture

To capture a PayPal Order that has been authorised send a request to /v1/payments/{paymentId}/capture.

📘

To capture an order that has been authorised separately, you need the associated BR-DGE paymentId that is returned when you authorised the order

You should expect to receive a response similar to the following

{  
  "code": "1000",  
  "message": "Approved",  
  "id": "6839c22206f97cc880001902830cb141",  
  "psp": {  
    "name": "PayPal-Direct"  
  }  
}

Retrieve a PayPal Order

You can retrieve the status of an order by providing the PayPal orderId as a path parameter to the
GET /v1/paypal/orders/{orderId} endpoint.

After calling this endpoint you should expect to receive a response similar to the following

{  
  "id": "6839c22206f97cc880001902830cb141",  
  "orderId": "50190127TN3647157",  
  "intent": "capture",  
  "status": "APPROVED",  
  "creationTimestamp": "2024-05-07T18:46:54Z",  
  "paymentSource": {  
    "name": "John Smith",  
    "email": "[email protected]",  
    "accountId": "QYR5Z8XBVJNXQ"  
  },  
  "purchaseUnits": [  
    {  
      "referenceId": "d9f80748-38f0-11e8-5467-8ed5f89c718b",  
      "description": "T-Shirt",  
      "customId": "123456789",  
      "invoiceId": "987654321",  
      "unitAmount": 100,  
      "unitTax": 0,  
      "currencyCode": "GBP"  
    }  
  ]  
}

PayPal orders can have any of the following status values as their status

StatusDescription
CREATEDThe order was created with the specified context.
PAYER_ACTION_REQUIREDThe order requires an action from the payer.
APPROVEDThe end user has approved the payment.
COMPLETEDA completed order can indicate a payment was authorised, an authorised payment was captured, or a payment was declined.

📘

Retrieving the status of a PayPal Order will always return the latest state of the Order.

Refund a PayPal payment

To refund a PayPal Order, use the paymentId returned from GET /v1/paypal/orders/{orderId}/payment

You then pass the paymentId as a path parameter to the POST /v1/payments/{paymentId}/refund endpoint to process a PayPal refund.

You should expect to receive a response similar to the following

{  
  "code": 1000,  
  "message": "Approved",  
  "id": "6839c22206f97cc880001902830cb141",  
  "psp": {  
    "name": "PayPal-Direct",  
    "transactionId": "a83a53a2-dcc8-45be-bf78-2b1e4b719f7c"  
  }  
}

Void an Authorised PayPal Order

To void an authorised PayPal Order, use the paymentId returned from GET /v1/paypal/orders/{orderId}/payment.

Pass the paymentId as a path parameter to the POST /v1/payments/{paymentId}/void endpoint to void an authorised PayPal payment.

You should expect to receive a response similar to the following

{  
  "code": 1000,  
  "message": "Approved",  
  "id": "6839c22206f97cc880001902830cb141",  
  "psp": {  
    "name": "PayPal-Direct",  
    "transactionId": "88365302-dcc8-45be-bf70-2b1e4b719f7c"  
  }  
}

Notifications

A subset of PayPal notifications are supported on the BR-DGE platform. The following notification types are currently supported by BR-DGE.

  • checkout.order.completed
  • checkout.order.approved
  • payment.capture.completed
  • payment.capture.denied
  • payment.capture.refunded
  • payment.capture.reversed
  • payment.authorization.created
  • payment.authorization.voided

You should expect PayPal notifications via BR-DGE to look similar to the following

{  
  "type": "payment",  
  "id": "166bf5e3-d1eb-4424-9815-b0871672269f",  
  "merchantAccountId": "paypaldirectpartnersandbox",  
  "code": "1000",  
  "status": "CAPTURED",  
  "psp": {  
    "name": "PayPal-Direct",  
    "transactionId": "4P989824YY471323N"  
  },  
  "message": "\\n \"id\": \"WH-8R63527673895222P-1851139778494754V\",\\n \"event_version\": \"1.0\",\\n \"create_time\": \"2024-01-24T14:10:24.883Z\",\\n \"resource_type\": \"capture\", \\n \"event_type\": \"PAYMENT.CAPTURE.COMPLETED\",\\n \"summary\": \"Payment completed for GBP 50.01\",\\n \"resource\":{\\n \"resource_version\":\"2.0\",\\n \"disbursement_mode\": \"INSTANT\",\\n \"payee\":{\\n \"email_address\": \"[email protected]\",\\n \"merchant_id\":\"6RZ25YB5RYBU6\"\\n },\\n \"amount\":{\\n \"value\": \"50.01\",\\n \"currency_code\": \"GBP\"\\n },\\n \"seller_protection\":{\\n \"dispute_categories\":[\n \"ITEM_NOT_RECEIVED\",\n \"UNAUTHORIZED_TRANSACTION\"\n ],\\n \"status\": \"ELIGIBLE\"\\n },\\n \"supplementary_data\": {\\n \"related_ids\": {\\n \"order_id\": \"53541605787289052\"\\n }\\n },\\n \"update_time\": \"2024-01-24T14:10:17Z\",\\n \"create_time\": \"2024-01-24T14:10:17Z\",\\n \"final_capture\": true,\\n \"seller_receivable_breakdown\":{\\n \"paypal_fee\":{\\n \"value\":\"1.90\",\\n \"currency_code\":\"GBP\"\\n },\\n \"gross_amount\":{\\n \"value\":\"50.01\",\\n \"currency_code\":\"GBP\"\\n },\\n \"net_amount\":{\\n \"value\":\"48.11\",\\n \"currency_code\":\"GBP\"\\n },\\n \"links\":[\n {\n \"rel\": \"self\",\n \"method\": \"GET\", \n \"href\": \"https://api.sandbox.paypal.com/v2/payments/captures/8XX9478741934354X\"\n },\n {\n \"rel\": \"refund\",\n \"method\": \"POST\",\n \"href\": \"https://api.sandbox.paypal.com/v2/payments/captures/8XX9478741934354X/refund\"\n },\n {\n \"rel\": \"up\",\n \"method\": \"GET\",\n \"href\": \"https://api.sandbox.paypal.com/v2/checkout/orders/7W06597080556272X\"\n }\n ]\\n },\\n \"status\": \"COMPLETED\"\\n },\\n \"links\":[\n {\n \"rel\": \"self\",\n \"method\": \"GET\",\n \"href\": \"https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-8M63527673895222P-1051139778494754V\"\n },\n {\n \"rel\": \"resend\",\n \"method\": \"POST\",\n \"href\": \"https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-8M63527673895222P-1051139770494754V/resend\"\n }\n ]\\n\\n\\n",  
  "hashCode": "HR8jFOBWN7BBQ5MNTDf/m1C61NNEXnS+FtfuII@YAzQ="  
}

The hashCode value can be calculated by following our dedicated Notification Hashing guide.

Support

To get started with PayPal via BR-DGE, or if you have any questions, please get in contact with support.

Updated 4 days ago