Orders

The orders object enables the merchant to create(POST), retrieve(GET) and update(PUT) a PayPal order. It generates vendor_order_number and vendor_approval_url. The vendor_order_number is a unique string ID referenced for any PayPal related transactions. 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 order object includes the vendor sub-object.

Orders 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

authorization_amount

The amount to be charged/credited to the customer.

decimal

R

order_number

A merchant-assigned unique ID code that is returned with the PayPal-create order response. Note: order_number is unique for each PayPal order and is identified as invoice number in PayPal[max length = 36]

string

o

vendor

The vendor object

vendor.vendor_type

The supported vendor types include the following.
• PayPal

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.locale

The locale parameter is used to specify the language and country for the paypal pages that the buyer will interact with during the payment process.
The supported values are:
• en_US
• fr_CA
• es_MX
Default value is: en_US

string

O

vendor.vendor_order_number

The approval URL is a web link provided by PayPal as part of the response when you create an order using this API. The buyer will be redirected to this URL to log in to their PayPal account, review the transaction details, and approve the payment.

string

-

vendor.vendor_approval_url

The approval URL is a web link provided by PayPal as part of the response when you create an order using this API. The buyer will be redirected to this URL to log in to their PayPal account, review the transaction details, and approve the payment.

string

-

vendor.vendor_order_status

The orders status
• PAYER_ACTION_REQUIRED : The order requires an action from the payer
• APPROVED : The customer approved the payment through the PayPal wallet
• COMPLETED : The payment was authorized or the authorized payment was captured for the order.

string

-

shipping_address

The Address Object

object

O

shipping_address.physical_address

The Physical Address Object.

object

R

shipping_address.first_name

The first name of the user associated with this shipping address [max length = 25].

string

R

shipping_address.last_name

The last name of the user associated with this shipping address [max length = 25].

string

R

shipping_address.physical_address.street_line1

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

string

R

shipping_address.physical_address.region

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

string

R

shipping_address.physical_address.locality

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

string

R

shipping_address.physical_address.region

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

string

R

shipping_address.physical_address.country

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

string

R

shipping_address.physical_address.postal_code

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

string

R

billing_address

The Address Object

object

-

billing_address.first_name

The first name of the user associated with this billing address [max length = 25].

string

-

billing_address.last_name

The last name of the user associated with this billing address [max length = 25].

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 Order with Shipping Address

				
					{{baseURI}}/organizations/org_organizationID/locations/loc_locationID/vendors/ven_{{merchantID}}/orders

This URI creates a PayPal vendor_order_number and vendor_approval_url.

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

Body (Raw)
				
					{
    "authorization_amount": 102.45,
    "order_number": "ORD123",
    "vendor": {
        "vendor_type": "paypal",
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl",
        "locale": "en-US",
        "vendor_account_email": "it@pp3.com"
    },
    "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"
        }
    }
}

Example Request

				
					curl --location -g '{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{locationID}/vendors/ven_{{merchantID}}/orders' \
--header 'Accept: application/json' \
--header 'Authorization: {{Authorization}}' \
--header 'X-Forte-Auth_Organization_Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "authorization_amount": 102.45,
    "order_number": "ORD123",
    "vendor": {
        "vendor_type": "paypal",
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl",
        "locale": "en-US",
        "vendor_account_email": "it@pp3.com"
    },
    "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"
        }
    }
}

'

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

POST Create orders without Shipping Address

				
					{{baseURI}}/organizations/org_organizationID/locations/loc_locationID/vendors/ven_{{merchantID}}/orders

This URI creates a PayPal vendor_order_number and returns vendor_approval_url.

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

Body (raw)

				
					{
    "authorization_amount": 102.45,
    "order_number": "ORD123",
    "vendor": {
        "vendor_type": "paypal",
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl",
        "locale": "en-US",
        "vendor_account_email": "it@pp3.com"
    }
}

Example Request

				
					curl --location -g '{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{locationID}/vendors/ven_{{merchantID}}/orders

' \
--header 'Accept: application/json' \
--header 'Authorization: {{Authorization}}' \
--header 'X-Forte-Auth_Organization_Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "authorization_amount": 102.45,
    "order_number": "ORD123",
    "vendor": {
        "vendor_type": "paypal",
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl",
        "locale": "en-US",
        "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=49D016001T440021E",
    "vendor_account_email": "it@pp3.com",
    "vendor_order_number": "49D016001T440021E",
    "vendor_order_status": "PAYER_ACTION_REQUIRED"
  },
  "response": {
    "environment": "live",
    "response_desc": "Create Successful."
  },
  "links": {
    "self": "https://api.forte.net/v3/organizations/org_334316/locations/loc_192642/vendors/ven_2TXS88UYGN8LE/orders/49D016001T440021E"
  }
}
Edit Content
Headers (12)

cache-control

no-cache

connection

keep-alive

content-type

application/json; charset=utf-8

date

Wed, 25 Oct 2017 19:03:26 GMT

expires

-1

pragma

no-cache

server

Microsoft-IIS/8.5

transfer-encoding

chunked

x-aspnet-version

4.0.30319

x-cdn

Incapsula

x-iinfo

7-16959006-16959017 NNNN CT(35 71 0) RT(1508958206196 41) q(0 0 1 -1) r(1 1) U16

x-powered-by

ASP.NET

GET Order by ID

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

This URI returns PayPal order details associated with vendor_order_number.
Orders can have the following statuses:

• PAYER_ACTION_REQUIRED: The order requires an action from the payer.
• APPROVED : The customer approved the payment through the PayPal wallet.
• COMPLETED : The payment was authorized and captured for the order.

NOTE: When the vendor_order_status is : “PAYER_ACTION_REQUIRED”, since the order is not yet approved, the billing or the shipping address will not be part of the response

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

Example Request

				
					curl --location -g '{{baseURI}}/organizations/org_organizationID/locations/loc_locationID/vendors/ven_{{merchantID}}/orders/{{ vendor_order_number }}' \
--header 'Accept: application/json' \
--header 'Authorization: {{Authorization}}' \
--header 'X-Forte-Auth_Organization_Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json'
'

Example Response

Edit Content 
				
					{
  "authorization_amount": 102.45,
  "location_id": "192642",
  "vendor": {
    "vendor_type": "paypal",
    "vendor_account_email": "it@pp3.com",
    "vendor_order_number": "49D016001T440021E",
    "vendor_order_status": "PAYER_ACTION_REQUIRED",
    "vendor_account_id": "2TXS88UYGN8LE"
  },
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "https://api.forte.net/v3/organizations/org_334316/locations/loc_192642/vendors/ven_2TXS88UYGN8LE/orders/49D016001T440021E"
  }
}
Edit Content
Click on the Edit Content button to edit/add the content.
Edit Content 
				
					{
  "authorization_amount": 102.45,
  "location_id": "192642",
  "vendor": {
    "vendor_type": "paypal",
    "vendor_account_email": "it@pp3.com",
    "vendor_order_number": "49D016001T440021E",
    "vendor_order_status": "APPROVED",
    "vendor_account_id": "2TXS88UYGN8LE"
  },
  "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_334316/locations/loc_192642/vendors/ven_2TXS88UYGN8LE/orders/49D016001T440021E"
  }
}
Edit Content
Click on the Edit Content button to edit/add the content.
Edit Content 
				
					{
  "authorization_amount": 102.45,
  "location_id": "192642",
  "vendor": {
    "vendor_type": "paypal",
    "vendor_account_email": "it@pp3.com",
    "vendor_order_number": "8XJ96991U0723350T",
    "vendor_order_status": "COMPLETED",
    "vendor_account_id": "2TXS88UYGN8LE"
  },
  "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"
    }
  },
  "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": "Get Successful."
  },
  "links": {
    "self": "https://api.forte.net/v3/organizations/org_334316/locations/loc_192642/vendors/ven_2TXS88UYGN8LE/orders/8XJ96991U0723350T"
  }
}
Edit Content
Click on the Edit Content button to edit/add the content.

PUT Update a PayPal Order

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

This URI updates the authorization_amount and shipping_address associated with the vendor_order_number.

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

Body raw

				
					{
    "vendor": {
        "vendor_type": "PayPal"
    },
    "authorization_amount": 109.45,
    "Shipping_address": {
        "first_name": "Marty",
        "last_name": "Mcly",
        "physical_address": {
            "street_line1": "8003 Clock Tower Ln",
            "street_line2": "Suite 200",
            "locality": "Allen",
            "region": "TX",
            "postal_code": "560018",
            "country": "US"
        }
    }
}

Example Request

				
					curl --location -g --request PUT '{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{locationID}/vendors/ven_{{merchantID}}/orders/{{vendor_order_number}}' \
--header 'Accept: application/json' \
--header 'Authorization: {{Authorization}}' \
--header 'X-Forte-Auth_Organization_Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json' \
--data '{
    "vendor": {
        "vendor_type": "PayPal"
    },
    "authorization_amount": 109.45,
    "Shipping_address": {
        "first_name": "Marty",
        "last_name": "Mcly",
        "physical_address": {
            "street_line1": "8003 Clock Tower Ln",
            "street_line2": "Suite 200",
            "locality": "Allen",
            "region": "TX",
            "postal_code": "560018",
            "country": "US"
        }
    }
}
'

Example Response

Edit Content 
				
					{
  "authorization_amount": 109.45,
  "location_id": "loc_242550",
  "vendor": {
    "vendor_type": "PayPal"
  },
  "Shipping_address": {
    "first_name": "Marty",
    "last_name": "Mcly",
    "physical_address": {
      "street_line1": "8003 Clock Tower Ln",
      "street_line2": "Suite 200",
      "locality": "Allen",
      "region": "TX",
      "postal_code": "560018",
      "country": "US"
    }
  },
  "response": {
    "environment": "live",
    "response_desc": "Update Successful."
  },
  "links": {
    "self": "https://api.forte.net/v3/organizations/org_300069/locations/loc_258750/vendors/ven_X8FJTTXPMDDWQ/orders/97D647112X2525015"
  }
}
Edit Content
Click on the Edit Content button to edit/add the content.
On this page