Use the Order API 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 URL
POST https://[reach_api_domain]/v1/orders
Numeric format
All decimals have a maximum precision of 2 digits. Fields (except for Discounts) will accept 0.00. For example, it lets you indicate that a customer's fee has been waived.
Country-specific parameters
The request will require specific parameters 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) | You must use 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) | Provide a valid ISO-3166-2 subdivision code (e.g., state or province) for the given country. Note that this field also accepts Mexican regions. |
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 theBillingProfile
object. You must pass on theBillingProfile
: if there is no existing customer profile.BillingProfileReference
: This is a free-text reference you may supply optionally when creating a new billing profile. This may refer to your 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 set up for this user, a contract ID can be sent instead of a Payment object. The ContractId must exist and not have expired, and if sent, the Payment object must not be included in the request.
Payment object
The payment object contains information related to the order and includes one of the fields: Online
, Offline
, or Card
. The specific fields included depend on the value of Payment.Type
—a value of "Online" indicates that you should include the Online
fields, while "Offline" or "Card" indicates you should include the corresponding fields.
For examples of the various fields we can accept for payment, see Payment object variationsP.
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.
Meta
The request allows you to submit free-form data in the Meta
field. This must be well-formed JSON, but the contents may be anything you wish. This can be used to return identifiers or supplemental information useful to your system.
Note
Please note that the Reach system will ignore any values within the
Meta
block.
Examples
Minimal request
This request contains a minimal number of fields required to create an order, without any previous profiles or contracts set up (note that the full BillingProfile and Payment objects are sent)
{
"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"
}
}
}
{
"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 of the optional fields. Note that as the whole 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.
{
"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"
}
}
}
{
"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 the 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.
{
"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"
}
}
}
{
"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"
}
}
{
"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"
}
{
"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 how 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.
{
"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"
}
}
}
{
"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 you have a successful profile created, you can use the BillingProfileReference
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.
{
"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"
}
}
}
{
"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.
{
"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"
}
}
}
{
"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 valid iterations of the payment object.
{
"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"
}
}
}
{
"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"
}
}
{
"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"
}
}
}
}
{
"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"
}
}
{
"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"
}
}
}
{
"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 typically come with an HTTP 200, with a JSON body. In these cases, you should make note of the returned OrderId
returned, this is the primary field you'll use to follow up on 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. However, the information that would normally populate the JSON body could not be constructed. You can still expect a typical lifecycle for these orders, including notifications; however, you may need to retrieve the order at a later date manually 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, contact Reach support.
HTTP 400 responses may indicate several 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), expect 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. The following table lists 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 that your total is a positive number |
AmountLimitExceeded | The total amount was greater than Reach can authorize for a single transaction. This may be processor or payment-type-dependent. |
|
AuthenticationInvalid | The ViaAgent flag was enabled, but this transaction is not authorized to use it. |
|
BirthDateInvalid | The birthdate was not present (for Brazil), or was invalid. |
|
Blacklisted | Reach has refused to approve the order because the consumer is on the Reach denylist. | Unrecoverable - Reach will refuse to honour requests for this consumer. Important: Do not share the notification with the customer. Doing so may aid parties that are attempting to carry out fraudulent activities. |
CaptureInvalid | A request has been sent with AutoCapture to 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. It 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, that is not in the past) |
ConsigneeInvalid | The shipping details contained invalid information. | This generic error indicates that the shipping details need to be validated. |
ConsumerInvalid | The billing profile contained invalid information | This generic error indicates that the billing profile must be validated. |
ConsumerNotFound | The consumer attempted to pay using Net Terms, but they do not have an account. |
|
ConsumerTotalInvalid | The total amount for the order was not usable. Possibly caused if the total (sum of items + taxes - discounts) <= 0 |
|
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 want 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. |
|
ContractNotFound | The ContractId supplied was not found |
|
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 extracted from the /fingerprint call is correct |
EmailAddressInvalid | The email address that was supplied was invalid | Resubmit the request with a valid email. Emails take the form @, with:
|
FraudSuspected | Reach refuses to honour the request due to the high risk of fraud. | Trying with a different payment method may work, but Reach will likely continue to reject orders for this consumer (dependent on specific fraud rules). Important: Do not share the notification with the customer. Doing so may aid parties that are attempting to carry out fraudulent activities. |
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 |
|
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). The 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 using the given payment method. |
|
PaymentAuthorizationFailed | A downstream payment processor declined the payment. | Submit the order again with a different payment method |
PaymentMethodUnsupported | The payment method submitted is unsupported. |
|
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 that 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-specific fields 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 using 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. See Retrieve an Orderdetails for more information.
Method URL
GET https://[reach_api_domain]/v1/orders/{OrderId}
Order ID
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 an HTTP 5xx-level error. These requests can be safely retried; however, if the issue persists, contact Reach support for help resolving it.
False negatives
Please note that orders that have been created through the Checkout API will throw a 404 on lookup. Please use the existing /query API to find these orders.
Example
POST https://[reach_api_domain]/v1/orders/88444a4d-09b5-440d-8011-755ab0a9d108
{
"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
Use the Capture endpoint to capture authorized funds and pre-authorized orders. This capture applies only to delayed capture orders where auto-capture is not configured, or AutoCapture
is set to false
in the request.
Method URL
POST https://[reach_api_domain]/v1/orders/{OrderId}/capture
Order ID
The OrderId
parameter corresponds to an OrderId
returned in a response from an order creation.
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
, it indicates that Reach needs to review the order before a capture can proceed manually. You should try to 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 in which these correspond to:
Code | Cause | Order state |
---|---|---|
AlreadyCancelled | The order was cancelled before the capture request was made | Cancelled |
PaymentFailed | The payment transaction for the order could not be captured. 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 denylist, 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 URL
DELETE https://[reach_api_domain]/v1/orders/{orderId}/cancel
Order ID
The OrderId
parameter corresponds to an OrderId
returned in a response from an order creation.
Response handling
Successful responses
Successful responses will 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.
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 business rules. |
AlreadyCommitted | The order has not been authorized and cannot be cancelled. However, you may cancel it 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 eitherSucceeded
orFailed
. See Refund states for more information on refund states.
Method URL
POST https://[reach_api_domain]/v1/orders/{OrderId}/refunds
Order ID
The OrderId
parameter corresponds to an OrderId
returned in a response from an order creation.
Response handling
Successful responses
Successful responses 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 HTTP 5xx-level error. These requests can be safely retried; however, if the issue persists, contact Reach support to help resolve it.
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 | A chargeback 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. For more information on state transitions, see Order states under States and notifications |
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. | Resubmit 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. If you want to reconfigure it, you will need to contact Reach support. |