Channel-Initiated Billing

DOCS

Last updated: Dec 20th, 6:20pm

Channel-Initiated Billing (CIB) is an agreement between you and your seller's buyers. Channels are nothing more than a chain or group of businesses, and those businesses are managed by you on your platform.

The buyer grants the channel permission to process third-party payments. A third-party payment is also known as a reference transaction. By establishing CIB, the buyer does not need to sign separate billing agreements with each seller on the channel.

To use CIB in your platform:

Before you can integrate Channel-Initiated Billing, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.
Then, return to this page to integrate Channel-Initiated Billing.

Create a billing agreement token.

Create a billing agreement.

Create an order.

Complete an order.

Create a billing agreement token

To create a billing agreement token, pass the agreement details including the description, payer, and billing plan in the JSON request body.

Set the payment_method parameter in the payer object to PAYPAL.

For example:

1curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/billing-agreements/agreement-tokens' \
2 -H "Content-Type: application/json" \
3 -d '{
4    "description": "Channel Billing Agreement",
5    "payer": {
6        "payment_method": "PAYPAL"
7    },
8    "plan": {
9        "type": "CHANNEL_INITIATED_BILLING",
10        "merchant_preferences": {
11            "return_url": "https://example.com/return",
12            "cancel_url": "https://example.com/cancel",
13            "notify_url": "https://example.com/notify",
14            "accepted_pymt_type": "INSTANT"
15        }
16    }
17}'

If your request for a billing agreement with the PayPal payment method succeeds, the API returns the HTTP 201 Created status code and a JSON response that includes an approval URL and billing agreement token details.

1{
2  "links": [
3    {
4      "href": "https://api-m.sandbox.paypal.com/agreements/approve?ba_token=BA-46438908592216253",
5      "rel": "approval_url",
6      "method": "POST"
7    },
8    {
9      "href": "https://api-m.sandbox.paypal.com/v1/billing-agreements/BA-46438908592216253/agreements",
10      "rel": "self",
11      "method": "POST"
12    }
13  ],
14  "token_id": "BA-46438908592216253"
15}

Create a billing agreement

After buyer approval, you use a billing agreement token to create the agreement.

Include the token in the URI:

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements \
2 -H 'Content-Type: application/json' \
3    -H 'Authorization: Bearer <Access-Token>' \
4  -d '{
5  "token_id": "BA-8A802366G0648845Y"
6}'

A successful request returns the HTTP 201 Created status code and a JSON response body that includes the billing agreement ID, the state of the agreement, which is ACTIVE, and information about the payer:

1{
2  "id": "B-8X5996561Y963560S",
3  "state": "ACTIVE",
4  "description": "Billing Agreement",
5  "payer":
6  {
7    "payer_info":
8    {
9      "email": "doe@example.com",
10      "first_name": "John",
11      "last_name": "Doe",
12      "payer_id": "ZU7HZ76P4VL5U"
13    }
14  },
15  "plan":
16  {
17    "type": "CHANNEL_INITIATED_BILLING",
18    "merchant_preferences":
19    {
20      "notify_url": "https://example.com/notify",
21      "accepted_pymt_type": "INSTANT"
22    }
23  },
24  "links": [
25  {
26    "href": "https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements/B-50V812176H0783741/cancel",
27    "rel": "cancel",
28    "method": "POST"
29  },
30  {
31    "href": "https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements/B-50V812176H0783741",
32    "rel": "self",
33    "method": "GET"
34  }],
35  "merchant":
36  {
37    "payee_info":
38    {
39      "email": "merchant@example.com"
40    }
41  },
42  "create_time": "2017-08-08T07:19:28.000Z",
43  "update_time": "2017-08-08T07:19:28.000Z"
44}

Save the id value, which is the billing agreement ID.

Next, you can use reference transaction to create an order.

Create an order

A v2/checkout/orders/ call creates an order with status of created. Save the associated order ID returned to pass to subsequent calls.

To create an order:

Include the Authorization, Accept, PayPal-Partner-Attribution-Id, and Content-Type headers in your request to POST /v2/checkout/orders/. For more information about these headers, see REST API authentication and headers.

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2  -H "Content-Type: application/json" \
3  -H "Accept: application/json" \
4  -H 'Authorization: Bearer <Access-Token>' \
5  -H "PayPal-Partner-Attribution-Id: EXAMPLE_MP" \
6  -d '{
7  "intent": "CAPTURE",
8    "purchase_units": [{
9      "amount": {
10        "currency_code": "USD",
11        "value": "100.00"
12      },
13      "payee": {
14        "email_address": "seller@example.com"
15      },
16      "payment_instruction": {
17        "disbursement_mode": "INSTANT",
18        "platform_fees": [{
19          "amount": {
20            "currency_code": "USD",
21            "value": "25.00"
22          },
23          "payee": {
24            "email_address": "seller@example.com"
25          }
26        }]
27      }
28    }]
29}'

A successful request returns the HTTP 201 Created status code and a JSON response body that includes the PayPal-generated order ID, an array of purchase unit objects, payment details, customer information, metadata, and order status.

1{
2  "id": "5O190127TN364715T",
3  "status": "COMPLETED",
4  "payer": {
5    "name": {
6      "given_name": "John",
7      "surname": "Doe"
8    },
9    "email_address": "customer@example.com",
10    "payer_id": "QYR5Z8XDVJNXQ"
11  },
12  "purchase_units": [{
13    "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
14    "shipping": {
15      "address": {
16        "address_line_1": "2211 N First Street",
17        "address_line_2": "Building 17",
18        "admin_area_2": "San Jose",
19        "admin_area_1": "CA",
20        "postal_code": "95131",
21        "country_code": "US"
22      }
23    },
24    "payments": {
25      "captures": [{
26        "id": "3C679366HH908993F",
27        "status": "COMPLETED",
28        "amount": {
29          "currency_code": "USD",
30          "value": "100.00"
31        },
32        "seller_protection": {
33          "status": "ELIGIBLE",
34          "dispute_categories": [
35            "ITEM_NOT_RECEIVED",
36            "UNAUTHORIZED_TRANSACTION"
37          ]
38        },
39        "final_capture": true,
40        "disbursement_mode": "INSTANT",
41        "seller_receivable_breakdown": {
42          "gross_amount": {
43            "currency_code": "USD",
44            "value": "100.00"
45          },
46          "paypal_fee": {
47            "currency_code": "USD",
48            "value": "3.00"
49          },
50          "net_amount": {
51            "currency_code": "USD",
52            "value": "97.00"
53          }
54        },
55        "create_time": "2018-04-01T21:20:49Z",
56        "update_time": "2018-04-01T21:20:49Z",
57        "links": [{
58            "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F",
59            "rel": "self",
60            "method": "GET"
61          },
62          {
63            "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
64            "rel": "refund",
65            "method": "POST"
66          }
67        ]
68      }]
69    }
70  }]
71}

Complete an order

To complete the order, call to v2/checkout/orders/{order_id}/capture to execute a payment. Pass the order ID in the request URL.

In addition to the standard Accept, Content-Type, PayPal-Request-Id, and Authorization headers, include the PayPal-Partner-Attribution-Id header.

Pass the billing agreement ID in the payment_source object in the JSON.

Request

1curl -v -k -X POST 'https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/capture' \
2 -H "PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a" \
3 -H "PayPal-Partner-Attribution-Id: Example_Marketplace" \
4 -H 'Authorization: Bearer <Access-Token>' \
5 -H "Content-Type: application/json" \
6 -H "Accept: application/json" \
7 -d '{
8       "payment_source": {
9         "token": {
10           "id": "B-8X5996561Y963560S",
11           "type": "BILLING_AGREEMENT"
12           }
13       }
14     }'

A successful request returns the HTTP 201 Created status code and a JSON response body that includes an id inside the payment's captures object. This ID is the seller's transaction ID and used for other operations on the captured payment, such as a refund or chargeback.

1{
2  "id": "5O190127TN364715T",
3  "status": "COMPLETED",
4  "payer": {
5    "name": {
6      "given_name": "John",
7      "surname": "Doe"
8    },
9    "email_address": "customer@example.com",
10    "payer_id": "QYR5Z8XDVJNXQ",
11    "phone": {
12      "phone_number": {
13        "national_number": "8882211161"
14      }
15    },
16    "address": {
17      "address_line_1": "2211 N First Street",
18      "address_line_2": "Building 17",
19      "admin_area_2": "San Jose",
20      "admin_area_1": "CA",
21      "postal_code": "95131",
22      "country_code": "US"
23    }
24  },
25  "purchase_units": [{
26    "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
27    "shipping": {
28      "method": "United States Postal Service",
29      "name": {
30        "full_name": "John Williams"
31      },
32      "address": {
33        "address_line_1": "2211 N First Street",
34        "address_line_2": "Building 17",
35        "admin_area_2": "San Jose",
36        "admin_area_1": "CA",
37        "postal_code": "95131",
38        "country_code": "US"
39      }
40    },
41    "payments": {
42      "captures": [{
43        "id": "3C679366HH908993F",
44         "status": "COMPLETED",
45         "amount": {
46           "currency_code": "USD",
47           "value": "100.00"
48         },
49         "seller_protection": {
50          "status": "ELIGIBLE",
51          "dispute_categories": [
52          "ITEM_NOT_RECEIVED",
53          "UNAUTHORIZED_TRANSACTION"
54        ]
55      },
56      "final_capture": true,
57      "seller_receivable_breakdown": {
58        "gross_amount": {
59          "currency_code": "USD",
60          "value": "100.00"
61         },
62         "paypal_fee": {
63           "currency_code": "USD",
64           "value": "3.00"
65         },
66         "payment_instruction": {
67           "platform_fees": [{
68             "amount": {
69               "currency_code": "USD",
70               "value": "25.00"
71             },
72             "payee": {
73               "email_address": "fee@example.com"
74             }
75             }]
76           },
77           "net_amount": {
78             "currency_code": "USD",
79             "value": "72.00"
80           }
81         },
82         "disbursement_mode": "INSTANT",
83         "create_time": "2018-04-01T21:20:49Z",
84         "update_time": "2018-04-01T21:20:49Z",
85         "links": [{
86           "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F",
87           "rel": "self",
88           "method": "GET"
89         },
90         {
91           "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
92            "rel": "refund",
93            "method": "POST"
94          }
95        ]
96        }]
97      }
98    }],
99  "links": [{
100    "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
101    "rel": "self",
102    "method": "GET"
103  }]
104}