Set up advanced credit and debit card payments

DocsCurrentLast updated: June 1st 2021, @ 10:02:46 am


Set up advanced payment options on your checkout page so your buyers can pay with debit and credit cards, PayPal, and alternative payment methods. You can customizes the card fields to align with your brand.

Know before you code

  • You must be an approved partner to use this integration.
  • Complete Onboard Sellers before you begin this integration. During seller onboarding, pass PPCP as the value for product name.
  • You must have an access token.
  • You must toggle on the Advanced Debit and Credit Card Payments setting in your REST app settings to use this integration.
  • This integration is a PCI Compliant - SAQ A solution for accepting credit card payments directly on your website.
  • Credit is a regulated activity in the UK. Before integrating a PayPal Credit button, you must be authorized to act as a credit broker and have a credit agreement with PayPal. For more information, contact business customer support through paypal.com or by calling 0800 358 7929.

1. Generate client token

Use the following code to request your client token:

curl -v -X POST https://api-m.sandbox.paypal.com/v1/identity/generate-token \
   -H 'Accept: application/json' \
   -H 'Accept-Language: en_US' \
   -H 'Authorization: Bearer <Access-Token>'
   -H 'Content-Type: application/json'

Step result

A successful request returns the client token and the number of seconds before the token expires.

Sample response

{
    "client_token": "eyJicmFpbnRyZWUiOnsiYXV0aG9yaXphdGlvbkZpbmdlcnByaW50IjoiYjA0MWE2M2JlMTM4M2NlZGUxZTI3OWFlNDlhMWIyNzZlY2FjOTYzOWU2NjlhMGIzODQyYTdkMTY3NzcwYmY0OHxtZXJjaGFudF9pZD1yd3dua3FnMnhnNTZobTJuJnB1YmxpY19rZXk9czlic3BuaGtxMmYzaDk0NCZjcmVhdGVkX2F0PTIwMTgtMTEtMTRUMTE6MTg6MDAuMTU3WiIsInZlcnNpb24iOiIzLXBheXBhbCJ9LCJwYXlwYWwiOnsiYWNjZXNzVG9rZW4iOiJBMjFBQUhNVExyMmctVDlhSTJacUZHUmlFZ0ZFZGRHTGwxTzRlX0lvdk9ESVg2Q3pSdW5BVy02TzI2MjdiWUJ2cDNjQ0FNWi1lTFBNc2NDWnN0bDUyNHJyUGhUQklJNlBBIn19",
    "expires_in": 3600
}

2. Load JavaScript SDK

Copy the following code to load the PayPal JavaScript SDK and modify it.

Sample request

<script src="https://www.paypal.com/sdk/js?components=hosted-fields&client-id=Client-ID&merchant-id=Merchant-ID&currency=USD&intent=capture" data-partner-attribution-id="BN-Code" data-client-token="Client-Token"</script>

Modify the code

After you copy the sample request, modify it depending on which type of onboarding you chose:

If you onboard sellers before payment

  • Pass the partner's client ID in the client-id query parameter. The client ID generates the access token required to make PayPal API calls in sandbox or production.

  • Pass the merchant ID of the seller you're facilitating a payment for in the merchant-id query parameter. The merchant ID is the seller's PayPal account ID. To get your seller's merchant ID, you can use one of the following:

    • read the merchantIdInPayPal query parameter attached to the return URL when the seller finishes PayPal onboarding and is redirected back to your site.
    • query it directly by the tracking_id you specified in the Partner Referrals call by calling GET /v1/customer/partners/partner_id/merchant-integrations?tracking_id={tracking_id}.
  • Change BN-Code to your PayPal Partner Attribution ID.
  • Set intent to capture to immediately capture funds.

If you build onboarding into your software

  • Pass your client ID in the client-id query parameter. The client ID generates the access token required to make PayPal API calls in sandbox or production.

  • Change BN-Code to your PayPal Partner Attribution ID.
  • Set intent to capture to immediately capture funds.

3. Render card fields

Copy the following code and modify it.

Sample request

<script src="https://www.paypal.com/sdk/js?components=hosted-fields&client-id=Client-ID&merchant-id=Merchant-ID&currency=USD&intent=capture" data-partner-attribution-id="BN-Code" data-client-token="Client-Token"</script>

<form id="my-sample-form">
  <label for="card-number">Card Number</label>
  <div id="card-number"></div>
  <label for="expiration-date">Expiration Date</label>
  <div id="expiration-date"></div>
  <label for="cvv">CVV</label>
  <div id="cvv"></div>
  <button value="submit" id="submit" class="btn">Pay with Card</button>
</form>

<script>
// Check if card fields are eligible to render for the buyer's country. The card fields are not eligible in all countries where buyers are located.
  if (paypal.HostedFields.isEligible() === true) {
    paypal.HostedFields.render({
      createOrder: function(data, actions) {
        return fetch('/my-server/create-order', {
            method: 'POST'
        }).then(function(res) {
            return res.json();
        }).then(function(data) {
            return data.id;
        });
      },
      styles: {
          'input': {
              'font-size': '14px',
              'font-family': 'Product Sans',
              'color': '#3a3a3a'
          },
          ':focus': {
              'color': 'black'
          }
      },
      fields: {
          number: {
              selector: '#card-number',
              placeholder: 'Credit Card Number',
          },
          cvv: {
              selector: '#cvv',
              placeholder: 'CVV',
          },
          expirationDate: {
              selector: '#expiration-date',
              placeholder: 'MM/YYYY',
          }
      }
    }).then(hostedFields => {
      document.querySelector('#my-sample-form').addEventListener('submit', event => {
        event.preventDefault();
        hostedFields.submit().then(payload => {
          return fetch('/my-server/handle-approve/' + payload.orderId, {
            method: 'POST'
           }).then(response => {
            if (!response.ok) {
              alert('Something went wrong');
            }
          });
        });
      });
    });
  }
</script>

Modify the code

After you copy the sample request, modify the code as follows:

  • Specify where to render the card fields using the fields key. This renders iframes hosted by PayPal that collects the buyer’s credit card information. These iframes allow you to customize the look and feel of your web page while ensuring that you are compliant with PCI requirements - SAQ A.
  • To capture funds using the buyer’s credit card information, you must implement a function to return an order ID for the value of the createOrder key. This function is called during the operation of hostedFields.submit(). In this example, the value of createOrder is a function that calls your server in order to get the order ID.
  • Upon successfully fulfilling hostedFields.submit(), the order status is set to APPROVED and funds are ready to be captured from the buyer. In this example, your server is set to immediately capture the order.
  • Optional: To set up payment buttons, you can set the components query parameter to buttons,hosted-fields when loading the PayPal JavaScript SDK.

Payment processor codes

Payment processors return the following codes when they receive a transaction request. For advanced card payments, the code displays in the authorization object under the response_code field.

This sample represents the processor response codes that are returned in the response of authorization and capture calls:

"processor_response": {
    "avs_code": "Y",
    "cvv_code": "S",
    "payment_advice_code": "",
    "response_code": "0000"
}

If an external payment processor declines a transaction, PayPal returns a HTTP 201 Created status code and a status of DECLINED in the capture status.

See the Orders API response_code object to get the processor response code for the non-PayPal payment processor errors.

See also