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 the BillingProfile object. You must pass on the BillingProfile: 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.

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.	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
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.	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 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 <local>@<domain>, 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 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.
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 either Succeeded or Failed. 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.