Skip to main content
Rate this article:

Overview

This tutorial takes you through the steps required to do your first transaction using PayPal billing agreement API with Verifone

What is a Billing Agreement and how does it work?

Billing Agreement API enables a customer and merchant to enter into a contract.

The merchant can bill a customer any time, without requiring a customer to login and authorize the transaction.

With a Billing Agreement the amount and the frequency of transactions aren't fixed. 

Examples

  • An agreement to pay eBay seller fees for listing items on eBay
  • An agreement between Uber and customer

In this scenarios, a customer gives his agreement only once, and later he doesn't have to authorize every time to PayPal. Billing the customer is done completely by merchant's side.

 

Step 1: Set up

Before making a transaction, you need:

  • PayPal account 
  • Valid JWT Token received from the entity service
  • paymentProviderContract. It is created as part of on-boarding merchant into Verifone via the Common Portal.

Step 2: Create a billing agreement token

First, we need to create a billing agreement token.

POST request URL: /billingAgreement/initiate

BODY:

{
    "ppcUid": "21261b6f-07df-4b63-3f4f-7fa0b83a20db",
    "description": "Stored PayPal account with The Partner merchant",
    "enableAddressChange": true,
    "returnUrl": "https://68f8497efb9ce8aeef3ed419c6ef0597.m.pipedream.net/success",
    "cancelUrl": "https://68f8497efb9ce8aeef3ed419c6ef0597.m.pipedream.net/cancel"
}

RESPONSE:

{
    "approvalUrl": "https://www.sandbox.paypal.com/agreements/approve?ba_token=BA-29L89918T33851208",
    "billingToken": "BA-29L89998T33851208"
}

Step 3: Approve token

Copy the approval Url from the step 2. Open the link in a browser. Login and approve the billing agreement token.

Note: Store billingToken as you will need it in step 4 for creating a billing agreement.

Step 4: Create a billing agreement

After approving with PayPal, use POST request with PPC and billingToken to create a Billing agreement.

POST request URL:

/billingAgreement/create

BODY:

{
    "billingToken":"BA-29L89998T33851208",
    "ppcUid":"21261b6f-07df-4b63-3f4f-7fa0b83a20db"
}

RESPONSE:

{
    "agreementId": {
        "id": "B-1WW844616B620123",
        "state": "ACTIVE",
        "description": "Stored PayPal account with The Partner merchant",
        "merchant": {
            "payeeInfo": {
                "email": "merchant@business.example.com"
            }
        },
        "payer": {
            "payerInfo": {
                "email": "payer@business.example.com",
                "firstName": "John",
                "lastName": "Doe",
                "payerId": "VJRXDDV4UWZ2W"
            }
        },
        "plan": {
            "merchantPreferences": {}
        },
        "createTime": "2021-03-03T11:56:27.000Z",
        "updateTime": "2021-03-03T11:56:27.000Z"
    }
}

 

Note: you need to store the billing agreement id, as you need it for making subsequent transactions.

 

Step 5: Create a transaction

Create a transaction that later will be used for capturing by billing agreement.

POST request URL:

/transactions

BODY:

{
    "context":  {
        "paymentProviderContract": "26761b6f-07df-4b63-9f4f-7fa0b83a20db"
    },
    "intent": "AUTHORIZE",
    "amount": {
        "currencyCode": "USD",
        "value": 20000
    },

    "applicationContext": {
    "returnUrl": "https://68f8497efb9ce8aeef3ed419c6ef0597.m.pipedream.net/success",
    "cancelUrl": "https://68f8497efb9ce8aeef3ed419c6ef0597.m.pipedream.net/cancel"
    },
    "shipping": {
        "address": {
            "country": "IN",
            "postalCode": "91",
            "countrySubdivision": "IN-MH",
            "city": "yyy",
            "addressLine1": "add1",
            "addressLine2": "add2"
        },
        "fullName": "JamesSmith"
    }
}

Response:

{
    "id": "e432ddb2-82a8-4213-a7da-8a7c0a3952de",
    "status": "INITIATED",
    "orderId": "1W065188KT702530J",
    "createdAt": "2021-03-25T13:56:27Z",
    "approvalUrl": "https://www.sandbox.paypal.com/checkoutnow?token=1W065188KT702530J"
}

Step 6: Authorize transaction by billing agreement

Use transaction id from step 5 and agreement Id from step 4

POST request URL:

/transactions/{TRANSACTION_ID}/authorize

Body:

{
    "agreementId":"B-1WW844616B620123"
}

Response:

{
    "id": "e123ddb2-82a8-4213-a7da-8a7c0a3952de",
    "authorizationId": "2JM15603JS454230B",
    "createdAt": "2021-03-25T14:00:46Z",
    "expiresAt": "2021-04-23T14:00:46Z",
    "status": "AUTHORISED",
    "payer": {
        "payerId": "VJRXDDV4UWZ4W",
        "shippingAddress": {
            "country": "IN",
            "postalCode": "400097",
            "countrySubdivision": "Maharashtra",
            "city": "Mumbai",
            "addressLine1": "Flat no. 507 Wing A Raheja Residency",
            "addressLine2": "Film City Road"
        }
    }
}

Step 7: Capture transaction by billing agreement

Use transaction id from step 5 and agreement Id from step 4.

POST request URL:

/transactions/{TRANSACTION_ID}/capture

Body:

{
    "agreementId":"B-1WW844616B620123"
}

Response:

{
    "id": "9512303c-c7a2-4417-8cdd-92a617890053",
    "captureId": "6CB11430732996717",
    "createdAt": "2021-03-25T14:07:23Z",
    "isFinalCapture": true,
    "status": "AUTHORISED"
}

 

Rate this article:
Logo of Verifone