DocumentationAPI Reference

Integrating fatzebra.js

Suggest Edits

Please make sure the following steps are completed in order to integrate PayPal using fatzebra.js:

1. Create an OAuth token (JWT)

Please follow the required steps in the Preparation section to generate an access token. The token needs to be stored in browser’s local storage with key fz-access-token prior to initialising fatzebra.js.

2. Include fatzebra.js JavaScript snippet

<!-- Sandbox -->
<script type="text/javascript" src="https://cdn.pmnts-sandbox.io/sdk/v1/fatzebra.js"></script>

<!-- Production -->
<script type="text/javascript" src="https://cdn.pmnts.io/sdk/v1/fatzebra.js"></script>

3. Initialise FatZebra

<body>
  <!-- This DIV element is used to load the PayPal button -->
  <div id="paypal-button-container"></div>
</body>

<script>
  const fz = new FatZebra({
    username: "<YOUR MERCHANT USERNAME>"
  })
</script>

4. Subscribe to FZ events (Refer to Events)

fz.on("fz.paypal.processing", function(event) {
  // Processing...
})

fz.on("fz.paypal.success", function(event) {
  // event.detail.data
})

fz.on("fz.paypal.error", function(event) {
  // event.detail.errors
})

fz.on("fz.paypal.cancel", function(event) {
  // event.detail.data.orderID
});

5. Create the required payment object

5.1 Order Checkout (Refer to PayPalPaymentObject)

Note: Please refer to our documentation for more information on how to calculate the verification HMAC. Alternatively refer to PaymentIntent.
(Pseudo code) verification = hmac_md5(shared_secret, "reference:amount:currency")

Note: All amount values should be in the smallest currency unit (eg., 100 to charge $1.00, or 100 to Charge ¥100, a zero decimal currency).

const paymentObject = {
  paymentIntent: {
    payment: {
      reference: "REF_123",
      amount: 12000,
      currency: "AUD",
    },
    verification: VERIFICATION_HMAC
  },
  paymentMethod: {
    type: "paypal_order",
    data: {
      intent: "capture",  // capture | authorize
      options: {
        brandName: "EXAMPLE BRAND NAME",
        payeePreferredPayment: "UNRESTRICTED"
      },
      purchases: [{
        description: "Sporting Goods",
        softDescriptor: "HighFashions",
        amount: {
            itemTotal: 9000,
            shipping: 2000,
            taxTotal: 1000
        },
        items: [
          {
            name: "T-Shirt",
            unitAmount: 9000,
            tax: 1000,
            qty: "1",
            category: "PHYSICAL_GOODS"
          }
        ],
        shippingAddress: {
          method: "United States Postal Service 1",
          address: {
            firstName: "John",
            lastName: "Doe",
            address_1: "100 Kent Street",
            address_2: "Cafe Lane",
            city: "Sydney",
            state: "NSW",
            postcode: "2000",
            country: "AU",
          }
        }
      }]
    }
  }
}

5.2 Billing Agreement (Refer to PayPalPaymentObject)

const paymentObject = {
  paymentMethod: {
    type: "paypal_billing",
    data: {
      name: "Sample Billing Agreement",
      description: "Stored PayPal account",
      shippingAddress: {
        firstName: "John",
        lastName: "Doe",
        address_1: "100 Kent Street",
        address_2: "Cafe Lane",
        city: "Sydney",
        state: "NSW",
        postcode: "2000",
        country: "AU",
      },
      merchantCustomData: "UUID"
    }
  }  
}

6. Render PayPal (setupPayPal)

🚧

Note

The setupPayPal() method should be called after setting up the event listeners!

// This method should be called after setting event listeners above!
fz.setupPayPal({
  currency: "AUD",
  payment: paymentObject,
  containerId: "paypal-button-container",
  style: {
    layout: "vertical",
    color: "blue",
    shape: "rect",
    label: "paypal"
  }  
})

Sample response payloads

1. PayPal Order (capture)

{
  message: "PayPal order approved.",
  data: {
    id: "123-PPO-NJV6YOCZ60J8NISE",
    reference: "ref_12345_281973",
    amount: 12000,
    decimalAmount: 120.0,
    successful: true,
    message: "Approved",
    currency: "AUD",
    transactionId: "123-PPO-NJV6YOCZ60J8NISE",
    transactionDate: "2020-08-27T15:14:22+10:00",
    intent: "Capture",
    paypalReference: "ref_12345_281973",
    invoiceId: "ref_12345_281973",
    billingAgreementId: null,
    status: "Completed",
    paymentSource: null,
    authorizedAmount: 0.0,
    capturedAmount: 120.0,
    refundedAmount: 0.0,
    authorizations: [],
    captures: [
      {
        id: "123-PPC-BHG8DOSWRCVLGZOK",
        status: "Completed",
        captured: true,
        amount: 12000,
        decimalAmount: 120.0,
        successful: true,
        currency: "AUD",
        transactionId: "123-PPC-BHG8DOSWRCVLGZOK",
        transactionDate: "2020-08-27T15:14:22+10:00",
        invoiceId: "ref_12345_281973",
        paypalFee: 318,
        sellerReceivableNetAmount: 11682,
        noteToPayer: "Sporting Goods",
        isFinalCapture: true
      }
    ],
    refunds: [],
    payer: {
      id: "29E2S1DN8P7FY",
      email: "[email protected]",
      address: { countryCode: "AU" }
    },
    payee: {
      id: "JEUIDZ5Q5JE0E",
      email: "[email protected]"
    }
  }
}

2. PayPal Billing Agreement

{
  message: "PayPal Billing Agreement created.",
  data: {
    id: "123-PBA-OPFHG40FRT6AHDENC",
    name: "Sample Billing Agreement",
    description: "Stored PayPal account",
    state: "Active",
    payer: {
      payerInfo: {
        email: "[email protected]",
        firstName: "Test Buyer",
        lastName: "Buyer",
        payerId: "4NGF92BA8UA5S"
      }
    },
    shippingAddress: {
      firstName: "John",
      lastName: "Doe",
      address_1: "100 Kent Street",
      address_2: "Cafe Lane",
      city: "Sydney",
      state: "NSW",
      postcode: "2000",
      country: "AU"
    },
    merchantCustomData: "",
    createdAt: "2020-08-27T15:15:13+10:00"
  }
}

Updated over 2 years ago