Order API Guide

Overview

The Order API is used by a merchant to manage an Order object. The Order object resembles the payment made by the consumer during the "Reach Drop-In" experience. Note that orders created through the Order API will not have associated sessions, and must be handled manually by you.

Create order

For request body, response body and errors, see the API documentation under Create a new order

Method

POST

Path

/v1/orders

Numeric format

All decimals have a max precision of 2 digits. Fields (with the exception of Discounts) will accept 0.00 - this will allow you to indicate, for example, that a fee has been waived for a customer.

Country specific parameters.

Certain parameters in the request will be required based on the customer's billing country. See the section under Country Specific Fields for more information on the specifics. The fields will all be contained within the BillingProfile object, and are as follows:

Field	Required for	Other Restrictions
Birthdate	Brazil (BR)	Format: YYYY-MM-DD (eg: 1982-01-21)
NationalIdentifier	Brazil, Argentina, India or Mexico (BR, AR, IN, MX)	Must be a valid format for the given country. See Country Specific Fields for more information on the accepted identifiers
Company	Brazil (BR) when a CNPJ is provided in the NationalIdentifier	---
Address.Region	Canada, Mexico, United States (CA, MX, US)	Must be a valid ISO-3166-2 subdivision code (eg: state, province) for the given country. Note that for Mexico, regions defined under Country Data are also accepted.
Address.PostCode	Brazil, Canada, Mexico, United States (BR, CA, MX, US)	---

Billing Profile

Customer billing information can be passed into the orders in a few ways. Valid billing profiles can be referenced by:

BillingProfile - The full customer billing information, as defined in the BillingProfile object. This must be passed in if there is no existing profile for the customer
BillingProfileReference - this is a free-text reference that you may optionally supply when creating a new billing profile. This may refer to your own internal customer ID, but the value must be unique within our system
BillingProfileId - this is a Reach-generated ID that refers to a previously generated Billing Profile.

Contract ID

If a contract has been setup for this user (see: Contracts for more information), then a contract ID can be sent in lieu of a Payment object. The ContractId must exist and not be expired, and if sent the Payment object must not be included in the request.

Payment Object

The payment object contains payment information for the order, and includes one of the fields Online, Offline or Card. The fields included is determined by value of Payment.Type - a value of "Online" indicates the Online fields should be included, likewise for "Offline" or "Card". Exactly one of these fields is expected.
See the subsection Examples - Payment Object to see examples of the various fields we can accept for payment

Device Fingerprint

For any requests where the ViaAgent flag is not set to true, a DeviceFingerprint must be supplied. See the section under /fingerprint for more information.

Examples

Minimal request

This request contains a minimal number of fields required to create an order, without any previous profiles or contracts setup (note that the full BillingProfile and Payment objects are sent)

Request

{
  "MerchantReference": "YourUniqueReference",
  "DeviceFingerprint": "b16f631b-931f-4bfb-adb4-402f94c3e49c",
  "Currency": "CAD",
  "Items": [
    {
      "Name": "Item 1",
      "Amount": 1.00,
      "Quantity": 1
    }
  ],
  "BillingProfile": {
    "BillingProfileReference": "YourIdentifier",
    "Name": "Al A. Peterson",
    "Email": "[email protected]",
    "Address": {
        "Street": "482 Billing St.",
        "City": "Edmonton",
        "Country": "ES"
      }
  },
  "Payment": {
    "Type": "CARD",
    "Method": "VISA",
    "Card": {
      "ReturnUrl": "http://some.return",
      "StashId": "8d12c2db-ed2f-4e89-b378-1"
    }
  }
}

Response

{
	"MerchantReference": "YourUniqueReference",
	"Currency": "CAD",
	"Items": [
		{
			"Name": "Item 1",
			"Amount": 1.0,
			"Quantity": 1
		}
	],
	"BillingProfile": {
		"Name": "Al A. Peterson",
		"Email": "[email protected]",
		"Address": {
			"Street": "482 Billing St.",
			"City": "Edmonton",
			"Country": "ES"
		}
		"BillingProfileReference": "YourIdentifier",
		"BillingProfileId": "083459a5-1d63-4105-ad99-f78200b97796"
	},
	"Payment": {
		"Type": "CARD",
		"Method": "VISA",
		"Card": {}
	},
	"RateOfferId": "19c8d54d-ffeb-4608-ab5c-3a36a868cccd",
	"State": "PAYMENTAUTHORIZED",
	"OrderId": "d45901d4-2805-40b4-83cc-94cd7fb0c780",
	"UnderReview": false,
	"Chargeback": false,
	"Expiry": "2022-06-14T19:26:47.404974Z",
	"Times": {
		"Created": "2022-06-07T19:26:45.697307Z",
		"Authorized": "2022-06-07T19:26:47.404974Z"
	}
}

Full Request

This request contains all optional fields possible. Note that as the full payment object is included, ContractId is not present. Similarly, as the full BillingProfile is included, the BillingProfierReference and BillingProfileId are not included at the root level of the request

Request

{
  "MerchantReference": "YourUniqueReference",
  "DeviceFingerprint": "b16f631b-931f-4bfb-adb4-402f94c3e49c",
  "Currency": "CAD",
  "Items": [
    {
      "Name": "Item 1",
      "Amount": 1.00,
      "Quantity": 1
    },
    {
      "Name": "Item 2",
      "Amount": 2.00,
      "Quantity": 2
    }
  ],
  "Discounts": [
    {
      "Name": "Discount 1",
      "Amount": 3.00
    }
  ],
  "ShippingDetails": {
    "ShippingAmount": 4.00,
    "DutyAmount": 5.00,
    "Name": "Margery Kershaw",
    "Email": "[email protected]",
    "Phone": "123-456-7890",
    "Address": {
      "Street": "45 Shipping Ave",
      "City": "Vancouver",
      "Region": "BC",
      "Country": "CA",
      "Postcode": "H0H0H0"
    }
  },
  "TaxAmount": 6.00,
  "BillingProfile": {
		"BillingReference": "ABillingReference",
    "Name": "Al A. Peterson",
    "Email": "[email protected]",
    "Phone": "9876543210",
    "Birthdate": "1980-01-02",
    "Address": {
        "Street": "482 Billing St",
        "City": "Edmonton",
        "Region": "AK",
        "Country": "US",
        "Postcode": "90210"
      }
    },
    "ViaAgent": true,
    "AcceptLiability": true,
    "AutoCapture": true,
    "OpenContract": true,
    "NotifyUrl": "http://url.notify",
    "Meta": {
			"field": "value"
		},
    "Payment": {
      "Type": "CARD",
      "Method": "VISA",
			"Card": {
				"ReturnUrl": "http://some.return",
				"StashId": "8d12c2db-ed2f-4e89-b378-1"
			}
    }
}

Response

{
	"MerchantReference": "YourUniqueReference",
	"Currency": "CAD",
	"Items": [
		{
			"Name": "Item 1",
			"Amount": 1.0,
			"Quantity": 1
		},
		{
			"Name": "Item 2",
			"Amount": 2.0,
			"Quantity": 2
		}
	],
	"BillingProfile": {
		"Name": "Al A. Peterson",
		"Email": "[email protected]",
		"Address": {
			"Street": "482 Billing St",
			"City": "Edmonton",
			"Country": "US",
			"Region": "AK",
			"Postcode": "90210"
		},
		"Birthdate": "1980-01-02",
		"Phone": "9876543210",
		"BillingProfileId": "1bf5369b-1883-4cfe-88ea-2f51d281d3c9"
	},
	"Payment": {
		"Type": "CARD",
		"Method": "VISA",
		"Card": {}
	},
	"ContractId": "e686c717-db95-4454-8cf0-914dc3ba7f43",
	"Discounts": [
		{
			"Name": "Discount 1",
			"Amount": 3.0
		}
	],
	"ShippingDetails": {
		"Name": "Margery Kershaw",
		"Email": "[email protected]",
		"Address": {
			"Street": "45 Shipping Ave",
			"City": "Vancouver",
			"Country": "CA",
			"Region": "BC",
			"Postcode": "H0H0H0"
		},
		"ShippingAmount": 4.0,
		"DutyAmount": 5.0,
		"Phone": "1234567890"
	},
	"TaxAmount": 6.0,
	"Meta": {
		"field": "value"
	},
	"RateOfferId": "19c8d54d-ffeb-4608-ab5c-3a36a868cccd",
	"State": "PAYMENTAUTHORIZED",
	"OrderId": "ad899992-b3de-447f-a6ea-6c3a1edace28",
	"UnderReview": false,
	"Chargeback": false,
	"Expiry": "2022-06-14T19:46:59.573010Z",
	"Times": {
		"Created": "2022-06-07T19:46:58.445940Z",
		"Authorized": "2022-06-07T19:46:59.573010Z"
	}
}

Using Contract ID

This example consists of 2 requests - the initial request sets OpenContract to true, which saves the payment method for later use; the second request uses the ContractId from the first response to use the saved payment for another request.

First Request

{
  "MerchantReference": "FirstRequest",
  "DeviceFingerprint": "b16f631b-931f-4bfb-adb4-402f94c3e49c",
  "Currency": "CAD",
  "Items": [
    {
      "Name": "Item 1",
      "Amount": 1.00,
      "Quantity": 1
    }
  ],
  "BillingProfile": {
    "Name": "Al A. Peterson",
    "Email": "[email protected]",
    "Address": {
        "Street": "482 Billing St",
        "City": "Edmonton",
        "Country": "ES"
      }
  },
	"OpenContract": true,
  "Payment": {
    "Type": "CARD",
    "Method": "VISA",
    "Card": {
      "ReturnUrl": "http://some.return",
      "StashId": "8d12c2db-ed2f-4e89-b378-1"
    }
  }
}

First Response

{
	"MerchantReference": "FirstRequest",
	"Currency": "CAD",
	"Items": [
		{
			"Name": "Item 1",
			"Amount": 1.0,
			"Quantity": 1
		}
	],
	"BillingProfile": {
		"Name": "Al A. Peterson",
		"Email": "[email protected]",
		"Address": {
			"Street": "482 Billing St",
			"City": "Edmonton",
			"Country": "ES"
		},
		"BillingProfileId": "5331aa9e-62f4-497d-b34d-55a03736c193"
	},
	"Payment": {
		"Type": "CARD",
		"Method": "VISA",
		"Card": {}
	},
	"ContractId": "5570c3fd-c83f-4f63-8731-b501e970cdc2",
	"RateOfferId": "19c8d54d-ffeb-4608-ab5c-3a36a868cccd",
	"State": "PAYMENTAUTHORIZED",
	"OrderId": "e05238c6-b708-49ac-b026-299ce93f34b3",
	"UnderReview": false,
	"Chargeback": false,
	"Expiry": "2022-06-14T21:07:20.417259Z",
	"Times": {
		"Created": "2022-06-07T21:07:19.306762Z",
		"Authorized": "2022-06-07T21:07:20.417259Z"
	}
}

Second Request

{
  "MerchantReference": "SecondRequest",
  "DeviceFingerprint": "b16f631b-931f-4bfb-adb4-402f94c3e49c",
  "Currency": "CAD",
  "Items": [
    {
      "Name": "Item 1",
      "Amount": 1.00,
      "Quantity": 1
    }
  ],
  "BillingProfile": {
    "Name": "Al A. Peterson",
    "Email": "[email protected]",
    "Address": {
        "Street": "482 Billing St",
        "City": "Edmonton",
        "Country": "ES"
      }
  },
	"ContractId": "5570c3fd-c83f-4f63-8731-b501e970cdc2"
}

Second Response

{
	"MerchantReference": "SecondRequest",
	"Currency": "CAD",
	"Items": [
		{
			"Name": "Item 1",
			"Amount": 1.0,
			"Quantity": 1
		}
	],
	"BillingProfile": {
		"Name": "Al A. Peterson",
		"Email": "[email protected]",
		"Address": {
			"Street": "482 Billing St",
			"City": "Edmonton",
			"Country": "ES"
		},
		"BillingProfileId": "c04b860b-dd80-469f-bbc9-52129886b95e"
	},
	"Payment": {
		"Type": "CARD",
		"Method": "VISA",
		"Card": {}
	},
	"ContractId": "5570c3fd-c83f-4f63-8731-b501e970cdc2",
	"RateOfferId": "19c8d54d-ffeb-4608-ab5c-3a36a868cccd",
	"State": "PAYMENTAUTHORIZED",
	"OrderId": "f2bf45e3-5a66-4a0b-90d3-8ec7eb1952f3",
	"UnderReview": false,
	"Chargeback": false,
	"Expiry": "2022-06-14T21:09:32.066523Z",
	"Times": {
		"Created": "2022-06-07T21:09:31.221643Z",
		"Authorized": "2022-06-07T21:09:32.066523Z"
	}
}

Billing Profile Variations

These examples show the different ways that a customer's billing information can be referenced. The initial request must use a full billing profile - this first request will show a minimal request with a billing profile provided, which also contains an optional BillingProfileReference in the request

Full BillingProfile Request

{
  "MerchantReference": "FullProfile",
  "DeviceFingerprint": "b16f631b-931f-4bfb-adb4-402f94c3e49c",
  "Currency": "CAD",
  "Items": [
    {
      "Name": "Item 1",
      "Amount": 1.00,
      "Quantity": 1
    }
  ],
  "BillingProfile": {
		"BillingProfileReference": "MerchantSuppliedReference",
    "Name": "Al A. Peterson",
    "Email": "[email protected]",
    "Address": {
        "Street": "482 Billing St",
        "City": "Edmonton",
        "Country": "ES"
      }
  },
  "Payment": {
    "Type": "CARD",
    "Method": "VISA",
    "Card": {
      "ReturnUrl": "http://some.return",
      "StashId": "8d12c2db-ed2f-4e89-b378-1"
    }
  }
}

Full BillingProfile Response

{
	"MerchantReference": "FullProfile",
	"Currency": "CAD",
	"Items": [
		{
			"Name": "Item 1",
			"Amount": 1.0,
			"Quantity": 1
		}
	],
	"BillingProfile": {
		"Name": "Al A. Peterson",
		"Email": "[email protected]",
		"Address": {
			"Street": "482 Billing St",
			"City": "Edmonton",
			"Country": "ES"
		},
		"BillingProfileReference": "MerchantSuppliedReference",
		"BillingProfileId": "cd8e09f0-3fc8-4ab2-84c8-8b8ed36db97a"
	},
	"Payment": {
		"Type": "CARD",
		"Method": "VISA",
		"Card": {}
	},
	"RateOfferId": "19c8d54d-ffeb-4608-ab5c-3a36a868cccd",
	"State": "PAYMENTAUTHORIZED",
	"OrderId": "b5539bb8-291d-4b1b-9657-a031cc09a644",
	"UnderReview": false,
	"Chargeback": false,
	"Expiry": "2022-06-14T21:20:51.357524Z",
	"Times": {
		"Created": "2022-06-07T21:20:49.977007Z",
		"Authorized": "2022-06-07T21:20:51.357524Z"
	}
}

This second request shows that, now that we have a successful profile created, we can use the BillingProfileReference we provided in the initial request to reference the same profile, instead of sending the full object. Note that the response contains the BillingProfile sent in the initial request.

Request using BillingProfileReference

{
  "MerchantReference": "ReferenceOnly",
  "DeviceFingerprint": "b16f631b-931f-4bfb-adb4-402f94c3e49c",
  "Currency": "CAD",
  "Items": [
    {
      "Name": "Item 1",
      "Amount": 1.00,
      "Quantity": 1
    }
  ],
  "BillingProfileReference": "MerchantSuppliedReference",
  "Payment": {
    "Type": "CARD",
    "Method": "VISA",
    "Card": {
      "ReturnUrl": "http://some.return",
      "StashId": "8d12c2db-ed2f-4e89-b378-1"
    }
  }
}

Response using BillingProfileReference

{
	"MerchantReference": "ReferenceOnly",
	"Currency": "CAD",
	"Items": [
		{
			"Name": "Item 1",
			"Amount": 1.0,
			"Quantity": 1
		}
	],
	"BillingProfile": {
		"Name": "Al A. Peterson",
		"Email": "[email protected]",
		"Address": {
			"Street": "482 Billing St",
			"City": "Edmonton",
			"Country": "ES"
		},
		"BillingProfileReference": "MerchantSuppliedReference",
		"BillingProfileId": "cd8e09f0-3fc8-4ab2-84c8-8b8ed36db97a"
	},
	"Payment": {
		"Type": "CARD",
		"Method": "VISA",
		"Card": {}
	},
	"RateOfferId": "19c8d54d-ffeb-4608-ab5c-3a36a868cccd",
	"State": "PAYMENTAUTHORIZED",
	"OrderId": "02fc49e9-719a-4b5e-94ac-18b230a421d6",
	"UnderReview": false,
	"Chargeback": false,
	"Expiry": "2022-06-14T21:23:54.045289Z",
	"Times": {
		"Created": "2022-06-07T21:23:52.999098Z",
		"Authorized": "2022-06-07T21:23:54.045289Z"
	}
}

Note that in all cases, the BillingProfileId is returned alongside the BillingProfile in the response. If you maintain this value, you can pass it in (similar to the BillingProfileReference) to specify the billing profile to use.

Request using BillingProfileId

{
  "MerchantReference": "BillingProfileIdOnly",
  "DeviceFingerprint": "b16f631b-931f-4bfb-adb4-402f94c3e49c",
  "Currency": "CAD",
  "Items": [
    {
      "Name": "Item 1",
      "Amount": 1.00,
      "Quantity": 1
    }
  ],
  "BillingProfileId": "cd8e09f0-3fc8-4ab2-84c8-8b8ed36db97a",
  "Payment": {
    "Type": "CARD",
    "Method": "VISA",
    "Card": {
      "ReturnUrl": "http://some.return",
      "StashId": "8d12c2db-ed2f-4e89-b378-1"
    }
  }
}

Response using BillingProfileId

{
	"MerchantReference": "BillingProfileIdOnly",
	"Currency": "CAD",
	"Items": [
		{
			"Name": "Item 1",
			"Amount": 1.0,
			"Quantity": 1
		}
	],
	"BillingProfile": {
		"Name": "Al A. Peterson",
		"Email": "[email protected]",
		"Address": {
			"Street": "482 Billing St",
			"City": "Edmonton",
			"Country": "ES"
		},
		"BillingProfileReference": "MerchantSuppliedReference",
		"BillingProfileId": "cd8e09f0-3fc8-4ab2-84c8-8b8ed36db97a"
	},
	"Payment": {
		"Type": "CARD",
		"Method": "VISA",
		"Card": {}
	},
	"RateOfferId": "19c8d54d-ffeb-4608-ab5c-3a36a868cccd",
	"State": "PAYMENTAUTHORIZED",
	"OrderId": "17c099bb-32ac-40d2-ba39-1580fb80d62f",
	"UnderReview": false,
	"Chargeback": false,
	"Expiry": "2022-06-14T21:27:23.969768Z",
	"Times": {
		"Created": "2022-06-07T21:27:22.672343Z",
		"Authorized": "2022-06-07T21:27:23.969768Z"
	}
}

Payment object variations

These examples will show some of the various iterations of the payment object that are valid.

Card (VISA) Request

{
  "MerchantReference": "VisaRequest",
  "DeviceFingerprint": "b16f631b-931f-4bfb-adb4-402f94c3e49c",
  "Currency": "CAD",
  "Items": [
    {
      "Name": "Item 1",
      "Amount": 1.00,
      "Quantity": 1
    }
  ],
  "BillingProfileId": "cd8e09f0-3fc8-4ab2-84c8-8b8ed36db97a",
  "Payment": {
    "Type": "CARD",
    "Method": "VISA",
    "Card": {
      "ReturnUrl": "http://some.return",
      "StashId": "8d12c2db-ed2f-4e89-b378-1"
    }
  }
}

Card (VISA) Response

{
	"MerchantReference": "VisaRequest",
	"Currency": "CAD",
	"Items": [
		{
			"Name": "Item 1",
			"Amount": 1.0,
			"Quantity": 1
		}
	],
	"BillingProfile": {
		"Name": "Al A. Peterson",
		"Email": "[email protected]",
		"Address": {
			"Street": "482 Billing St",
			"City": "Edmonton",
			"Country": "ES"
		},
		"BillingProfileReference": "MerchantSuppliedReference",
		"BillingProfileId": "cd8e09f0-3fc8-4ab2-84c8-8b8ed36db97a"
	},
	"Payment": {
		"Type": "CARD",
		"Method": "VISA",
		"Card": {}
	},
	"RateOfferId": "19c8d54d-ffeb-4608-ab5c-3a36a868cccd",
	"State": "PAYMENTAUTHORIZED",
	"OrderId": "f1ff1797-233f-4834-80d2-1856d21b3147",
	"UnderReview": false,
	"Chargeback": false,
	"Expiry": "2022-06-14T21:46:53.148116Z",
	"Times": {
		"Created": "2022-06-07T21:46:52.015492Z",
		"Authorized": "2022-06-07T21:46:53.148116Z"
	}
}

Online (iDeal) Request

{
  "MerchantReference": "IdealRequest",
  "DeviceFingerprint": "b16f631b-931f-4bfb-adb4-402f94c3e49c",
  "Currency": "EUR",
  "Items": [
    {
      "Name": "Item 1",
      "Amount": 1.00,
      "Quantity": 1
    }
  ],
  "BillingProfileId": "127a2b9b-e140-496a-8c31-351dd42c9deb",
  "Payment": {
    "Type": "ONLINE",
    "Method": "IDEAL",
        "Online": {
            "Locale": "en-us",
            "ReturnUrl": "http://return.url",
            "Ideal": {
                "IssuerId": "Knab"
            }   
        }
    
  }
}

Online (iDeal) Response

{
	"MerchantReference": "IdealRequest",
	"Currency": "EUR",
	"Items": [
		{
			"Name": "Item 1",
			"Amount": 1.0,
			"Quantity": 1
		}
	],
	"BillingProfile": {
		"Name": "Desmond Longo",
		"Email": "[email protected]",
		"Address": {
			"Street": "482 Billing St",
			"City": "Edmonton",
			"Country": "NL"
		},
		"Birthdate": "1980-01-02",
		"Phone": "9876543210",
		"BillingProfileId": "127a2b9b-e140-496a-8c31-351dd42c9deb"
	},
	"Payment": {
		"Type": "ONLINE",
		"Method": "IDEAL",
		"Online": {}
	},
	"RateOfferId": "66ad3834-b35e-4e81-8b7c-5986cbc56197",
	"State": "PROCESSING",
	"OrderId": "391b60a7-fd34-4cad-8251-cc8958af7d30",
	"UnderReview": false,
	"Chargeback": false,
	"Expiry": "2022-06-08T00:12:16.000000Z",
	"Action": {
		"Redirect": "https://sandbox.withreach.com/auth/e66a5978-d06a-4231-a6e3-f1f239ef4c44"
	},
	"Times": {
		"Created": "2022-06-07T22:12:15.367736Z"
	}
}

Offline (Bank Transfer) Request

{
  "MerchantReference": "BankRequest",
  "DeviceFingerprint": "b16f631b-931f-4bfb-adb4-402f94c3e49c",
  "Currency": "EUR",
  "Items": [
    {
      "Name": "Item 1",
      "Amount": 1.00,
      "Quantity": 1
    }
  ],
  "BillingProfileId": "e313b6dc-3b4b-436b-ae00-080acfffcb54",
  "Payment": {
    "Type": "OFFLINE",
    "Method": "BANK",
		"Offline": {
			"ReturnUrl": "http://return.url"
		}
  }
}

Offline (Bank Transfer) Response

{
	"MerchantReference": "BankRequest",
	"Currency": "EUR",
	"Items": [
		{
			"Name": "Item 1",
			"Amount": 1.0,
			"Quantity": 1
		}
	],
	"BillingProfile": {
		"Name": "Gino Lombardo",
		"Email": "[email protected]",
		"Address": {
			"Street": "482 Billing St",
			"City": "Edmonton",
			"Country": "DE"
		},
		"Birthdate": "1980-01-02",
		"Phone": "9876543210",
		"BillingProfileId": "e313b6dc-3b4b-436b-ae00-080acfffcb54"
	},
	"Payment": {
		"Type": "OFFLINE",
		"Method": "BANK",
		"Offline": {}
	},
	"RateOfferId": "66ad3834-b35e-4e81-8b7c-5986cbc56197",
	"State": "PROCESSING",
	"OrderId": "52767191-13bf-4698-ab81-257621822d7b",
	"UnderReview": false,
	"Chargeback": false,
	"Expiry": "2022-07-07T22:09:43.000000Z",
	"Action": {
		"Display": {
			"AccountHolder": "Global Collect B.V.",
			"AccountNumber": "115241904",
			"BankName": "Postbank AG",
			"City": "Leipzig",
			"Country": "Germany",
			"Iban": "DE53860100900115241904",
			"PaymentReference": "626300212459",
			"SwiftCode": "PBNKDEFF",
			"ExtraBankData": "BLZ|86010090"
		}
	},
	"Times": {
		"Created": "2022-06-07T22:09:42.979988Z"
	}
}

Response Handling

See the section under "response" in the Create a new order section of the API documentation for defined responses.

Successful responses

Successful responses will typically come with an HTTP 200, with a JSON body. In these cases, you should make note of the OrderId we've returned, this is the primary field you'll use if you wish to follow up any API requests against this order (cancelling, lookups, capture, etc).
Note that it is sometimes possible to receive an HTTP 201 with only the OrderId. This is rare, but it indicates that the order was successful, but the information that would normally populate the JSON body could not be constructed. You can still expect a normal lifecycle for these orders - including notifications - however, you may need to manually retrieve the order at a later date should you require more information.

Failure responses

Failure responses will come with either an HTTP 4xx or 5xx level status. See the section "Responses" under Create a new order for a definition of the response, but they will always contain (at the very least) the following:

Code - this field is intended as an easily parseable string for consumption by your code. Use this for programmatic decisions on handling the failure responses.
Message - this is a human-readable string meant to give more information for debugging. It is not recommended to use this for decisions in code.

HTTP 500 responses indicate a server error. We recommend retrying requests if an HTTP 500 is received - if failures persist, please contact Reach support.
HTTP 400 responses may indicate a number of problems that are actionable by the client. For requests that contain an invalid format (such as a string instead of a numeric, or a non-optional field being omitted), expected a response with an error code of INVALID_REQUEST and a list of field errors indicating the precise problem. For example:

{
	"Code": "INVALID_REQUEST",
	"Message": "Invalid request syntax",
	"FieldErrors": [
		{
			"Code": "FIELD_MISSING",
			"Message": "Currency is a required field",
			"Field": "Currency"
		},
		{
			"Code": "VALIDATION_ERROR",
			"Message": "At least 1 item is required",
			"Field": "Items"
		}
	]
}

HTTP 4xx level responses may also be returned for client-level errors other than simple request validation errors. See the following table for a list of possible errors, their causes and possible remediation steps.

Code	Cause	Remediation
AmountInvalid	The total amount for the order was not usable. Possibly caused if the total (sum of items + taxes - discounts) <= 0	Validate your total is a positive number
AmountLimitExceeded	The total amount was greater than Reach is able to authorize for a single transaction. This may be processor or payment-type dependent.	Split the request into multiple orders Attempt the payment again with a different method
AuthenticationInvalid	The `ViaAgent` flag was enabled but this transaction is not authorized to use it.	Verify with Reach that you are authorized to utilize the `ViaAgent` flag. Attempt the order again with `ViaAgent` disabled/omitted
BirthDateInvalid	The birthdate was not present (for Brazil), or was invalid	Verify the birthdate is being sent. Verify the format is YYYY-MM-DD (eg, 1982-12-31) Ensure the birthdate is valid (eg, not in the future)
Blacklisted	Reach has refused to approve the order because the consumer is on the Reach blacklist.	Unrecoverable - Reach will refuse to honour requests for this consumer. It is important that you do not communicate the user is blacklisted to avoid tipping-off
CaptureInvalid	A request has been sent with `AutoCapture` true, but this cannot be honoured	Omit `AutoCapture` or set to false
CardExpired	The payment card has expired and the order cannot be authorized	Submit the request with a different card or payment type
CardMonthInvalid	The payment card expiry details contained an invalid month.	Ensure the month is a numeric value (01-12), and a valid month. Ensure that the correct expiry was entered during the call to the Stash
CardNameInvalid	The name in the payment card details is not valid.	Ensure that the name submitted to the Stash is associated with the given card number
CardNumberInvalid	The payment card number was entered incorrectly. This may have failed a Luhn check, or was declined by a downstream processor/bank.	Re-submit the corrected number via the Stash call
CardYearInvalid	The payment card expiry details contained an invalid year	Ensure that the correct expiry for the given card number was entered during the call to the Stash (ie: a 2 digit year this is not in the past)
ConsigneeInvalid	The shipping details contained invalid information.	This is a generic error indicating that the shipping details need to be validated
ConsumerInvalid	The billing profile contained invalid information	This is a generic error indicating that the billing profile needs to be validated
ConsumerNotFound	The consumer attempted to pay with Net Terms, but they do not have an account	Prompt the consumer to sign up for Net Terms and re-submit Submit the order with a different payment method
ConsumerTotalInvalid	The total amount for the order was not usable. Possibly caused if the total (sum of items + taxes - discounts) <= 0	Validate that the correct discounts have been applied Validate that the correct items are being charged
ContractClosed	A `ContractId` was specified, however this contract is marked as Closed at Reach	Submit the request again with the `Payment` block information supplied. Set `OpenContract=true` if you with to open a new contract for this payment information
ContractCurrencyMismatch	The payment information associated with the `ContractId` you provided does not match the `Currency` in the request.	Modify the request to use the same Currency as the `ContractId`. Submit the request again with the `Payment` block information supplied. Set `OpenContract=true` if you with to open a new contract for this payment information
ContractNotFound	The `ContractId` supplied was not found	Verify the `ContractId` is correct Submit the request again with the `Payment` block information supplied. Set `OpenContract=true` if you with to open a new contract for this payment information
CountryInvalid	The country supplied in the billing profile was invalid	Verify the country is correct. Ensure it is a proper ISO-3166 2-character country code
Invalid ConsumerCurrency	The `Currency` was unknown or unsupported.	Submit the request again with a different `Currency`. See Currencies and Countries for supported currencies.
CurrencyNotFound	The `Currency` was unknown or unsupported.	Submit the request again with a different `Currency`. See Currencies and Countries for supported currencies
CardVerificationCodeInvalid	The CVV/CVC2 was incorrect.	Submit the stash request again with the correct CVV/CVC2, then resubmit the order
DeviceNotFound	The `DeviceFingerprint` submitted was not found.	Ensure the `DeviceFingerprint` call was made first, and the correct value extracted. See /fingerprint
Invalid Device Fingerprint	The `DeviceFingerprint` had an invalid format`	Ensure that the fingerprint you've extract from the /fingerprint call is correct
EmailAddressInvalid	The email address that was supplied was invalid	Re-submit the request with a valid email. Emails take the form @, with: Maximum 64 characters for segment prior to "@" Maximum 256 characters after "@" including the domain Validated by the following regex: `^([a-zA-Z0-9!#$%&\+\-/=?^_\.{\|}~])+@+([a-zA-Z0-9\.\-])$`
FraudSuspected	Reach refuses to honour the request due to high risk of fraud.	Trying with a different payment method may work, but it is likely that Reach will continue to reject orders for this consumer (dependent on specific fraud rules). It is important that you do not communicate fraud is suspected to avoid tipping-off
InsufficientFunds	The specified payment method does not have enough funds to cover the order	Submit the request with a different payment method
InvalidCurrency	The currency is not supported	Submit the request with a different currency. See Currencies and Countries for supported currencies. Attempt the same order with a different payment method
IssuerInvalid	An `Offline` payment has been made but the `IssuerId` is incorrect.	Submit the request with a valid `IssuerId` (may be dependent on the consumer country). Issuer should be returned from a /getPaymentMethods call. Submit the request with a different payment method
NationalIdentifierInvalid	The `NationalIdentifier` was submitted but was determined to be invalid.	Ensure the user has submitted a valid National ID for the given country. Refer to Country Specific Fields for the accepted IDs
OpenContractInvalid	A contract cannot be opened for the given payment method.	Submit the request with `OpenContract` omitted or false Submit the request with a different payment method
PaymentAuthorizationFailed	The payment was declined by a downstream payment processor.	Submit the order again with a different payment method
PaymentMethodUnsupported	The payment method submitted is unsupported.	Ensure you are setup to use the given payment method Validate the consumer country Submit the request with a different payment method
PaymentFailed	The payment was authorized but could not be captured.	Attempt to capture the order manually (see the section under capture order
PostalCodeInvalid	The `PostCode` field was invalid	Verify the postal code is formatted correctly for the given country
RegionInvalid	The `Region` field was invalid	Verify the `Region` is valid for the given country. See Country Data for a list of supported regions

Payment Authorization Failure:

The following errors will be returned with a 400 HTTP status from Order API in the event a /checkout request fails at Payment Authorization.

Most can be remediated by making another payment attempt with a different payment method.

Code	Message
DoNotHonour	Action Declined, do not honor
DeclinedByIssuer	Declined by issuing bank
AccountLimitExceeded	Amount exceeds shopper account limit
RestrictedCard	Restricted card
InsufficientFunds	Insufficient funds
Unauthorized	Processing not permitted/authorized
RefusedByProcessor	Refused by processor
SuspectedFraud	Suspected fraud by processor
ConsumerNotFound	Consumer not found
InvalidCurrency	Invalid currency
ProcessorSystemError	Processor system error
CancelledAtBank	Cancelled at payment provider or bank
CurrencyNotSupported	Processor does not support currency or method
Referral	Referral requested; not enough information
DeclinedByAcquirer	Declined by acquiring bank
InvalidCustomerData	Invalid customer data
CardholderNameMissing	Card holder name missing
CardholderAccountInvalid	Card holder account not valid credit account
CountryNotSupported	Processor does not support country
NotATestCard	Card is not a test card
AuthorizationExpired	Authorization expired before capture
PayPalMethodFailed	PayPal method failed
CardNoLongerValid	Card number no longer valid
AuthenticationFailed	Authentication failed
SoftDecline	Authentication required

Retrieve Order

Lookup information about an order. For the API definition, see the section under Retrieve an Order.

Method

GET

Path

/v1/orders/{OrderId}

The OrderId parameter corresponds to an OrderId returned in a response from an order creation.

Response Handling

Successful Responses

Successful responses will always be returned with an HTTP 200 status. Reach will return all possible information about the order in a successful response.

Failure Responses

Orders that cannot be found will throw an HTTP 404.
Server failures will result in some sort of HTTP 5xx level error. These requests can be safely retried, however if the issue persists please contact Reach support to help resolve.

🚧
False Negatives
Please note that orders that have been created through the Checkout Integration will throw a 404 on lookup. Please use the existing /query API to find these orders.

Example

POST to /v1/orders/88444a4d-09b5-440d-8011-755ab0a9d108

Response:

{
	"MerchantReference": "GetAnOrder",
	"Currency": "CAD",
	"Items": [
		{
			"Name": "Item 1",
			"Amount": 1.0,
			"Quantity": 1
		},
		{
			"Name": "Item 2",
			"Amount": 2.0,
			"Quantity": 2
		}
	],
	"BillingProfile": {
		"Name": "Al A. Peterson",
		"Email": "[email protected]",
		"Address": {
			"Street": "452 Billing St",
			"City": "Edmonton",
			"Country": "US",
			"Region": "AK",
			"Postcode": "90210"
		},
		"Birthdate": "1980-01-02",
		"Phone": "9876543210",
		"BillingProfileId": "491e5987-2fd6-44ea-af56-ae83f38aee58"
	},
	"Payment": {
		"Type": "CARD",
		"Method": "VISA",
		"Card": {}
	},
	"ContractId": "b0bce2ab-132c-428c-9a67-c03773a8a6cc",
	"Discounts": [
		{
			"Name": "Discount 1",
			"Amount": 3.0
		}
	],
	"ShippingDetails": {
		"Name": "Margery Kershaw",
		"Email": "[email protected]",
		"Address": {
			"Street": "45 Shipping Ace",
			"City": "Vancouver",
			"Country": "CA",
			"Region": "BC",
			"Postcode": "H0H0H0"
		},
		"ShippingAmount": 4.0,
		"DutyAmount": 5.0,
		"Phone": "1234567890"
	},
	"TaxAmount": 6.0,
	"Meta": {
		"field": "value"
	},
	"RateOfferId": "19c8d54d-ffeb-4608-ab5c-3a36a868cccd",
	"State": "PROCESSED",
	"OrderId": "88444a4d-09b5-440d-8011-755ab0a9d108",
	"UnderReview": false,
	"Chargeback": false,
	"Expiry": "2022-06-15T22:03:17.857177Z",
	"Times": {
		"Created": "2022-06-08T22:03:16.546246Z",
		"Authorized": "2022-06-08T22:03:17.857177Z",
		"Processed": "2022-06-08T22:03:26.572014Z"
	}
}

Capture Order

Capture a pre-authorized order; this applies only to delayed capture orders.

Method

POST

Path

/v1/orders/{OrderId}/capture

The OrderId parameter corresponds to an OrderId returned in a response from an order creation.

Usage

The Capture endpoint can be used to capture funds that have been authorized. This is only valid if you are not configured to use auto-capture, and/or if AutoCapture is false in the request. Otherwise, funds will be captured automatically and this endpoint can be ignored.

Response Handling

Successful Responses

Successful responses will be returned with an HTTP 200 status code. Verify that the order status in the body is PROCESSED, and if so you can mark the order as completed in your system

Under Review

If an HTTP 409 is returned with an error code of UNDER_REVIEW, this indicates that Reach needs to do a manual review of the order before a capture can proceed. You should try and capture the funds again at a later time.

Failure Responses

Failures will generally be returned with an HTTP 500 to indicate that the capture cannot proceed. The following table outlines codes and causes of these errors, as well as the order state these correspond to:

Code	Cause	Order state
AlreadyCancelled	The order was cancelled before the capture request was made	Cancelled
PaymentFailed	The payment transaction could not be captured for the order. This could be due to administrative or policy actions within Reach, an error at the payment method provider, or other reasons. The Message element may contain additional information.	ProcessingFailed
Blacklisted	The consumer is on the Reach blacklist and Reach has refused to process the order.	ProcessingFailed
FraudSuspected	Based on the parameters of the order, Reach suspects that the order is fraudulent and/or represents too high a risk to proceed with processing.	ProcessingFailed

Examples

All requests represent a POST to /v1/orders/88444a4d-09b5-440d-8011-755ab0a9d108/capture

Captured

Returns with an HTTP 200

{
	"OrderState": "PROCESSED"
}

UnderReview

Returns with an HTTP 409

{
 "Code": "UnderReview",
 "Message": "The order is under review and may not be captured until the review is completed."
}

Cancel Order

Cancel an order that has been authorized but not captured.

Method

DELETE

Path

v1/orders/{orderId}/cancel

The OrderId parameter corresponds to an OrderId returned in a response from an order creation.

Response Handling

Successful responses

Successful responses will simply return an HTTP 204 with an empty response body. This indicates that the specified order is now Cancelled in the Reach system. The order can still be queried, but no action may be taken on it.

Failure Responses

The cancel may fail and return a 409 if the order is in a state that cannot be cancelled. The nature of the failure can be determined from the error code.

Code	Description
AlreadyCaptured	The order has been captured already - either by a manual capture request, or for a request where the `AutoCapture` was set to true.
AlreadyDeclined	The order has been declined due to some sort of business rules.
AlreadyCommitted	The order has not been authorized and cannot be cancelled. You may be able to cancel this once it is authorized.

Refund

Create a new refund against an order.

📘
Refunds are asynchronous
It is important to note that a success from this endpoint does not mean that the refund has been approved, only that it has been queued in the system and created in a state of InProgress. Expect an asynchronous notification once the refund has moved to either Succeeded or Failed. See States and Events for more information on refund states.

Method

POST

Path

/v1/orders/{OrderId}/refunds
The OrderId parameter corresponds to an OrderId returned in a response from an order creation.

Response Handling

Successful responses

Successful responses will typically come with an HTTP 200, with a JSON body. In these cases, please make note of the RefundId field returned as this will be used to identify the refund in the expected asynchronous notifications.
Note that in some rare cases it is possible to receive an HTTP 201 with only the RefundId in the response, due to certain system degradation. In this case you may follow-up with a call to retrieve an order, the refund will be expected in the Refunds block of this response.

Failure responses

If the order specified in the path cannot be found, expect an HTTP 404.
Server failures will result in some sort of HTTP 5xx level error. These requests can be safely retried, however if the issue persists please contact Reach support to help resolve.
Other client-level errors are expected to throw an HTTP 400. See the following table for expected codes, causes and remediation steps

Code	Cause	Remediation
ChargebackExists	There is a chargeback that has been issued against the order. Refunds cannot be created against disputed orders.	N/A
OrderStateInvalid	The order is not in either `PROCESSED` or `DECLINED` state.	Wait for the order to be captured or declined, then re-issue the refund. See Order States under States and Events for more information on state transitions.
ReferenceIdInvalid	The `RefundReference` has a restricted string.	Ensure that the `RefundReference` does not start with the string "INTERPAY" and re-submit the refund request.
ReferenceIdMismatch	There is already a refund under this order with the given `RefundReference`	Re-submit the refund request with a unique `RefundReference`. Note that if the refund is `InProgress` you may not see this error.
RefundLimitExceeded	This amount of this refund request would be greater than the sum of the order items, less any discounts or existing refunds, and would put this order in the negative.	Re-submit the refund for a lesser amount.
RefundPeriodEnded	Refunds can no longer be issued against this order as the merchant-configured refund period has ended.	This refund cannot be resubmitted. You will need to contact reach support if you wish to reconfigure this.

Overview

Create order

Method

Path

Numeric format

Country specific parameters.

Billing Profile

Contract ID

Payment Object

Device Fingerprint

Meta

Examples

Minimal request

Full Request

Using Contract ID

Billing Profile Variations

Payment object variations

Response Handling

Successful responses

Failure responses

Payment Authorization Failure:

Retrieve Order

Method

Path

Response Handling

Successful Responses

Failure Responses

🚧False Negatives

Example

Capture Order

Method

Path

Usage

Response Handling

Successful Responses

Under Review

Failure Responses

Examples

Captured

UnderReview

Cancel Order

Method

Path

Response Handling

Successful responses

Failure Responses

Refund

📘Refunds are asynchronous

Method

Path

Response Handling

Successful responses

Failure responses

🚧
False Negatives

📘
Refunds are asynchronous