Agreements

The agreements object enables the merchant to create(POST) and retrieve(GET) a paypal token. It generates a vendor_billing_agreement_token and vendor_approval_url. The vendor_billing_agreement_token is a unique string token generated by PayPal. It can be used to create PayPal paymethods. The vendor_approval_url is a web link, that enables the merchants to direct their users to log into PayPal account, review the transaction details and approve the payment. Once the payment is approved by the users on their PayPal account, merchants can redirect the buyers back to their preferred web page by specifying the same in the return_url. The agreements object includes the vendor sub-object.

Agreements Object

Parameter

Description

Type

Req

organization_id

The identification number of the associated organization. For example, org_5551236.

string

R

location_id

The identification number of the associated location. For example, loc_1234568.

string

R

vendor

The vendor object

vendor.vendor_type

The supported vendor types include the following.
• paypal

string

R

vendor.vendor_account_email

The email address of merchant linked to the PayPal account

string

R

vendor.return_url

The URL where the customer is redirected after the customer approves the payment.

string

R

vendor.cancel_url

The URL where the customer is redirected after the customer cancels the payment.

string

R

vendor.vendor_approval_url

This URL is where you redirect to the buyer to obtain their approval for the payment .The buyer will be redirected to this URL to log in to their PayPal account, review the transaction details, and approve the payment.

string

R

vendor.vendor_token_status

The orders status
•PENDING:The token approval is pending.
•APPROVED:The token is approved.

string

-

vendor.vendor_billing_agreement_token

The ID of paypal billing agreement token.

string

-

billing_address

The Address Object

object

-

billing_address.first_name

The first name of the user associated with this billing address [max length = 25]. NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens.

string

-

billing_address.last_name

The last name of the user associated with this billing address [max length = 25]. NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens

string

-

billing_address.phone

The phone number associated with this billing address. This field supports both U.S. and Canadian phone numbers. [max length = 15

string

-

billing_address.email

The email address associated with this billing address. [max length = 50]

string

-

billing_addreess.physical_address

The Physical Address Object.

Object

-

billing_address.physical_address.street_line1

The first line of the street address. [max length = 35]

string

-

billing_address.physical_address.street_line2

The second line of the street address. [max length = 35]

string

-

billing_address.physical_address.locality

Locality or city/town/village. [max length = 25]

string

-

billing_address.physical_address.region

Region or state/province. This field supports both U.S. and Canadian regions. [max length = 2]

string

-

billing_address.physical_address.country

The ISO 3166-1 alpha-2 country abbreviation. [max length = 2]

string

-

billing_address.physical_address.postal_code

Postal Code [max length = 15]. This field supports both U.S. and Canadian postal codes.

string

-

POST Create Agreement Token

				
					{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/vendors/ven_{{merchantID}}/agreements

This URI creates vendor_billing_agreement_token and returns approval_url.

AUTHORIZATION Basic Auth
Username {{apiaccessid}}
Password {{apisecurekey}}

Body raw
				
					{
    "vendor": {
        "vendor_type": "PayPal",
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl",
        "vendor_account_email": "it@pp3.com"
    }
}

Example Request

				
					curl --location -g '{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/vendors/ven_{{merchantID}}/agreements' \
--header 'Accept: application/json' \
--header 'Authorization: {{Authorization}}' \
--header 'X-Forte-Auth_Organization_Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "vendor": {
        "vendor_type": "PayPal",
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl",
        "vendor_account_email": "it@pp3.com"
    }
}

'

Example Response

Edit Content 
				
					{
  "authorization_amount": 102.45,
  "order_number": "ORD123",
  "vendor": {
    "vendor_type": "paypal",
    "vendor_approval_url": "https://www.sandbox.paypal.com/checkoutnow?token=4FY371515P9080118",
    "vendor_account_email": "it@pp3.com",
    "vendor_order_number": "4FY371515P9080118",
    "vendor_order_status": "PAYER_ACTION_REQUIRED"
  },
  "shipping_address": {
    "first_name": "Emmett",
    "last_name": "Brown",
    "physical_address": {
      "street_line1": "SA Line 1",
      "street_line2": "SA Line 2",
      "locality": "Allen",
      "region": "TX",
      "postal_code": "560018",
      "country": "US"
    }
  },
  "response": {
    "environment": "live",
    "response_desc": "Create Successful."
  },
  "links": {
    "self": "https://api.forte.net/v3/organizations/org_334316/locations/loc_192642/vendors/ven_2TXS88UYGN8LE/orders/4FY371515P9080118"
  }
}
Edit Content
Headers (1)
Content-Type
 

application/json

GET Agreement Token by ID

				
					{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/vendors/ven_{{merchantID}}/agreements/agg_{{vendor_billing_agreement_token}}

This URI returns paypal agreement token details associated with vendor_billing_agreement_token.
agreement token can have the following statuses:

• PENDING: The token approval is pending.
• APPROVED.: The token is approved.

AUTHORIZATION Basic Auth
Username {{apiaccessid}}
Password {{apisecurekey}}

Example Request

				
					curl --location -g '{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/vendors/ven_{{merchantID}}/agreements/agg_{{vendor_billing_agreement_token}} ' \
--header 'Accept: application/json' \
--header 'Authorization: {{Authorization}}' \
--header 'X-Forte-Auth_Organization_Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json'

Example Response

Agreement Token by ID-Approved

				
					{ {
    "location_id": "loc_192642",
    "vendor": {
        "vendor_type": "paypal",
        "vendor_account_id": "2TXS88UYGN8LE",
        "vendor_billing_agreement_token": "BA-6RR2783828950364P",
        "vendor_token_status": "APPROVED"
    },
    "billing_address": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "sb-ymx43p27176890@personal.example.com",
        "physical_address": {
            "street_line1": "500, W Bethany Street",
            "street_line2": "123",
            "locality": "Allen",
            "region": "TX",
            "postal_code": "75013",
            "country": "US"
        }
    },
    "response": {
        "environment": "live",
        "response_desc": "Get Successful."
    },
    "links": {
        "self": "https://api.forte.net/v3/organizations/org_300005/locations/loc_192642/vendors/ven_2TXS88UYGN8LE/agreements/agg_BA-6RR2783828950364P"
    }
}

Example Response

Agreement Token by ID-Pennding

				
					{
  "location_id": "loc_234234",
  "vendor": {
    "vendor_type": "payPal",
    "vendor_account_id": "2TXS88UYGN8LE",
    "vendor_billing_agreement_token": "BA-6RR2783828950364P",
    "vendor_token_status": "PENDING"
  },
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "https://api.forte.net/v3/organizations/org_300005/locations/loc_192642/vendors/ven_2TXS88UYGN8LE/agreements/agg_BA-6RR2783828950364P"
  }
}
On this page