--- updatedAt: 2026-03-17T00:00:21.000Z agentTools: projectIndex: https://docs.withreach.com/llms.txt --- # Order API guide Use the Order API to manage an `Order` object. The `Order` object resembles the payment made by the customer 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 ```http 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. ## 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. You must pass on the `BillingProfile` if there is no existing customer profile. * `BillingProfileReference`: This is an optional free-text reference you may supply 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 `BillingProfile`. View the [Billing profile variations](https://docs.withreach.com/reference/order-api-guide-1#billing-profile-variations) section for examples. ### Country-specific parameters The country entered in the`BillingProfile.Address` dictates the required and optional fields within the `BillingProfile` object. For example, if the `Country` field contains Brazil's country code (BR), then a valid birthdate is required in the `BillingProfile.Birthdate` field. Review [Country-specific fields](https://docs.withreach.com/reference/country-specific-fields-1) for the complete list of country-dependent fields in the `BillingProfile` object. ## 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 variations](#payment-object-variations). ## Device fingerprint For any requests where the `ViaAgent` flag is not set to true, a `DeviceFingerprint` must be supplied. See the section under [/fingerprint](https://docs.withreach.com/reference/fingerprint-1) 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. 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) ```json Minimal JSON 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": "bill@email.com", "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" } } } ``` ```json Minimal JSON response { "MerchantReference": "YourUniqueReference", "Currency": "CAD", "Items": [ { "Name": "Item 1", "Amount": 1.0, "Quantity": 1 } ], "BillingProfile": { "Name": "Al A. Peterson", "Email": "bill@email.com", "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. ```json Full JSON 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": "marge@email.com", "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": "bill@email.com", "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" } } } ``` ```json Full JSON 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": "bill@email.com", "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": "marge@email.com", "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. ```json First JSON 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": "bill@email.com", "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" } } } ``` ```json First JSON response { "MerchantReference": "FirstRequest", "Currency": "CAD", "Items": [ { "Name": "Item 1", "Amount": 1.0, "Quantity": 1 } ], "BillingProfile": { "Name": "Al A. Peterson", "Email": "bill@email.com", "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" } } ``` ```json Second JSON 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": "bill@email.com", "Address": { "Street": "482 Billing St", "City": "Edmonton", "Country": "ES" } }, "ContractId": "5570c3fd-c83f-4f63-8731-b501e970cdc2" } ``` ```json Second JSON request { "MerchantReference": "SecondRequest", "Currency": "CAD", "Items": [ { "Name": "Item 1", "Amount": 1.0, "Quantity": 1 } ], "BillingProfile": { "Name": "Al A. Peterson", "Email": "bill@email.com", "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. ```json Full billing profile request { "MerchantReference": "FullProfile", "DeviceFingerprint": "b16f631b-931f-4bfb-adb4-402f94c3e49c", "Currency": "CAD", "Items": [ { "Name": "Item 1", "Amount": 1.00, "Quantity": 1 } ], "BillingProfile": { "BillingProfileReference": "SupplierSuppliedReference", "Name": "Al A. Peterson", "Email": "bill@email.com", "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" } } } ``` ```json Full billing profile response { "MerchantReference": "FullProfile", "Currency": "CAD", "Items": [ { "Name": "Item 1", "Amount": 1.0, "Quantity": 1 } ], "BillingProfile": { "Name": "Al A. Peterson", "Email": "bill@email.com", "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. ```json BillingProfileReference request { "MerchantReference": "ReferenceOnly", "DeviceFingerprint": "b16f631b-931f-4bfb-adb4-402f94c3e49c", "Currency": "CAD", "Items": [ { "Name": "Item 1", "Amount": 1.00, "Quantity": 1 } ], "BillingProfileReference": "SupplierSuppliedReference", "Payment": { "Type": "CARD", "Method": "VISA", "Card": { "ReturnUrl": "http://some.return", "StashId": "8d12c2db-ed2f-4e89-b378-1" } } } ``` ```json BillingProfileReference response { "MerchantReference": "ReferenceOnly", "Currency": "CAD", "Items": [ { "Name": "Item 1", "Amount": 1.0, "Quantity": 1 } ], "BillingProfile": { "Name": "Al A. Peterson", "Email": "bill@email.com", "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. ```json BillingProfileId request { "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" } } } ``` ```json BillingProfileId response { "MerchantReference": "BillingProfileIdOnly", "Currency": "CAD", "Items": [ { "Name": "Item 1", "Amount": 1.0, "Quantity": 1 } ], "BillingProfile": { "Name": "Al A. Peterson", "Email": "bill@email.com", "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. ```json Visa (CARD) 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" } } } ``` ```json Visa (CARD) response { "MerchantReference": "VisaRequest", "Currency": "CAD", "Items": [ { "Name": "Item 1", "Amount": 1.0, "Quantity": 1 } ], "BillingProfile": { "Name": "Al A. Peterson", "Email": "bill@email.com", "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" } } ``` ```json iDEAL (ONLINE) 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" } } } } ``` ```json iDEAL (ONLINE) request { "MerchantReference": "IdealRequest", "Currency": "EUR", "Items": [ { "Name": "Item 1", "Amount": 1.0, "Quantity": 1 } ], "BillingProfile": { "Name": "Desmond Longo", "Email": "desmond@longowatchrepair.com", "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" } } ``` ```json Bank Transfer (BANK) 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" } } } ``` ```json Bank Transfer (BANK) request { "MerchantReference": "BankRequest", "Currency": "EUR", "Items": [ { "Name": "Item 1", "Amount": 1.0, "Quantity": 1 } ], "BillingProfile": { "Name": "Gino Lombardo", "Email": "gino@nassau.edu", "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](https://docs.withreach.com/reference/createorder) 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](https://docs.withreach.com/reference/createorder) 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: ```json Invalid request { "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.
  • 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 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](https://docs.withreach.com/docs/stash).
CardNameInvalid The name in the payment card details is not valid. Ensure that the name submitted to the [Stash](https://docs.withreach.com/docs/stash) is associated with the given card number.
CardNumberInvalid The payment card number was entered incorrectly. It may have failed a [Luhn](https://en.wikipedia.org/wiki/Luhn_algorithm) check, or was declined by a downstream processor/bank. Re-submit the corrected number via the [Stash](https://docs.withreach.com/docs/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](https://docs.withreach.com/docs/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.
  • 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 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.
  • 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](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) 2-character country code.
Invalid ConsumerCurrency The `Currency` was unknown or unsupported. Submit the request again with a different `Currency`. See [Currencies and Countries](https://docs.withreach.com/docs/supported-countries-and-currencies) for supported currencies.
CurrencyNotFound The `Currency` was unknown or unsupported. Submit the request again with a different `Currency`. See [Currencies and Countries](https://docs.withreach.com/docs/supported-countries-and-currencies) 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](https://docs.withreach.com/reference/fingerprint-1)
Invalid Device Fingerprint The `DeviceFingerprint` had an invalid format. Ensure that the fingerprint you've extracted from the [/fingerprint](https://docs.withreach.com/reference/fingerprint-1) call is correct
EmailAddressInvalid The email address that was supplied was invalid. Resubmit 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 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.
  • 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). The issuer should be returned from a [/getPaymentMethods](https://docs.withreach.com/reference/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.
  • Submit the request with OpenContract omitted or false
  • Submit the request with a different 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.
  • 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](https://docs.withreach.com/reference/order-api-guide-1#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 Order details for more information. ## Method URL ```http 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](#create-order). ## 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. Please note that orders that have been created through the [Checkout API](https://dash.readme.com/project/withreach/v2.23/docs/checkout-api) will throw a 404 on lookup. Please use the existing [/query](https://docs.withreach.com/reference/query) API to find these orders. ### Example ```http POST /orders/{OrderId} request POST https://[reach_api_domain]/v1/orders/88444a4d-09b5-440d-8011-755ab0a9d108 ``` ```json POST /orders/{OrderId} 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": "bill@email.com", "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": "marge@email.com", "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](https://docs.withreach.com/docs/getting-started-drop-in#step-2-integrating-drop-in-with-auto-or-delayed-capture) orders where auto-capture is not configured or `AutoCapture` is set to `false` in the request. ## Method URL ```http 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](https://docs.withreach.com/reference/order-api-guide-1#create-order). ## 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. ```json Captured { "OrderState": "PROCESSED" } ``` ### UnderReview Returns with an HTTP 409. ```json Under review { "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 ```http 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](#create-order). ## Response handling ### Successful responses Successful responses will return an HTTP 204 with an empty response body. This indicates that the specified order is `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. 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 [Refund states](https://docs.withreach.com/docs/states-and-notifications#refund-states) for more information on refund states. ## Method URL ```http 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](#create-order). ## 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](#retrieve-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](https://docs.withreach.com/docs/states-and-notifications#order-states) under [States and notifications](https://docs.withreach.com/docs/states-and-notifications-for-drop-in)
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 supplier-configured refund period has ended. This refund cannot be resubmitted. If you want to reconfigure it, you will need to contact Reach support.