HomeDocumentationAPI Reference
API Reference

Order API guide

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:

FieldRequired forOther Restrictions
BirthdateBrazil (BR)Format: YYYY-MM-DD (eg., 1982-01-21)
NationalIdentifierBrazil, 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
CompanyBrazil (BR), when a CNPJ is provided in the NationalIdentifier***
Address.RegionCanada, 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.PostCodeBrazil, 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.

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.

CodeCauseRemediation
AmountInvalidThe total amount for the order was not usable. Possibly caused if the total (sum of items + taxes - discounts) <= 0Validate that your total is a positive number
AmountLimitExceededThe 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




AuthenticationInvalidThe 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




BirthDateInvalidThe 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)




BlacklistedReach 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.
CaptureInvalidA request has been sent with AutoCapture to true, but this cannot be honouredOmit AutoCapture or set to false
CardExpiredThe payment card has expired, and the order cannot be authorizedSubmit the request with a different card or payment type
CardMonthInvalidThe 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
CardNameInvalidThe name in the payment card details is not valid.Ensure that the name submitted to the Stash is associated with the given card number
CardNumberInvalidThe 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
CardYearInvalidThe payment card expiry details contained an invalid yearEnsure 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)
ConsigneeInvalidThe shipping details contained invalid information.This generic error indicates that the shipping details need to be validated.
ConsumerInvalidThe billing profile contained invalid informationThis generic error indicates that the billing profile must be validated.
ConsumerNotFoundThe 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




ConsumerTotalInvalidThe 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




ContractClosedA ContractId was specified, however, this contract is marked as Closed at ReachSubmit the request again with the Payment block information supplied. Set OpenContract=true if you want to open a new contract for this payment information
ContractCurrencyMismatchThe 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




ContractNotFoundThe 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




CountryInvalidThe country supplied in the billing profile was invalidVerify the country is correct. Ensure it is a proper ISO-3166 2-character country code
Invalid ConsumerCurrencyThe Currency was unknown or unsupported.Submit the request again with a different Currency. See Currencies and Countries for supported currencies.
CurrencyNotFoundThe Currency was unknown or unsupported.Submit the request again with a different Currency. See Currencies and Countries for supported currencies
CardVerificationCodeInvalidThe CVV/CVC2 was incorrect.Submit the stash request again with the correct CVV/CVC2, then resubmit the order
DeviceNotFoundThe DeviceFingerprint submitted was not found.Ensure the DeviceFingerprint call was made first, and the correct value extracted. See /fingerprint
Invalid Device FingerprintThe DeviceFingerprint had an invalid format`Ensure that the fingerprint you've extracted from the /fingerprint call is correct
EmailAddressInvalidThe email address that was supplied was invalidResubmit 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\.\-])*$




FraudSuspectedReach 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.
InsufficientFundsThe specified payment method does not have enough funds to cover the orderSubmit the request with a different payment method
InvalidCurrencyThe 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




IssuerInvalidAn 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
NationalIdentifierInvalidThe 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
OpenContractInvalidA 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




PaymentAuthorizationFailedA downstream payment processor declined the payment.Submit the order again with a different payment method
PaymentMethodUnsupportedThe 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




PaymentFailedThe payment was authorized but could not be captured.Attempt to capture the order manually (see the section under capture order.
PostalCodeInvalidThe PostCode field was invalidVerify that the postal code is formatted correctly for the given country
RegionInvalidThe Region field was invalidVerify 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.

CodeMessage
DoNotHonourAction Declined, do not honor
DeclinedByIssuerDeclined by issuing bank
AccountLimitExceededAmount exceeds shopper account limit
RestrictedCardRestricted card
InsufficientFundsInsufficient funds
UnauthorizedProcessing not permitted/authorized
RefusedByProcessorRefused by processor
SuspectedFraudSuspected fraud by processor
ConsumerNotFoundConsumer not found
InvalidCurrencyInvalid currency
ProcessorSystemErrorProcessor system error
CancelledAtBankCancelled at payment provider or bank
CurrencyNotSupportedProcessor does not support currency or method
ReferralReferral requested; not enough information
DeclinedByAcquirerDeclined by acquiring bank
InvalidCustomerDataInvalid customer data
CardholderNameMissingCard holder name missing
CardholderAccountInvalidCard holder account not valid credit account
CountryNotSupportedProcessor does not support country
NotATestCardCard is not a test card
AuthorizationExpiredAuthorization expired before capture
PayPalMethodFailedPayPal method failed
CardNoLongerValidCard number no longer valid
AuthenticationFailedAuthentication failed
SoftDeclineAuthentication 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:

CodeCauseOrder state
AlreadyCancelledThe order was cancelled before the capture request was madeCancelled
PaymentFailedThe 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
BlacklistedThe consumer is on the Reach denylist, and Reach has refused to process the order.ProcessingFailed
FraudSuspectedBased 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.

CodeDescription
AlreadyCapturedThe order has been captured already - either by a manual capture request, or for a request where the AutoCapture was set to true.
AlreadyDeclinedThe order has been declined due to some business rules.
AlreadyCommittedThe 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

CodeCauseRemediation
ChargebackExistsA chargeback has been issued against the order. Refunds cannot be created against disputed orders.N/A
OrderStateInvalidThe 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
ReferenceIdInvalidThe RefundReference has a restricted string.Ensure that the RefundReference does not start with the string "INTERPAY" and re-submit the refund request.
ReferenceIdMismatchThere is already a refund under this order with the given RefundReferenceRe-submit the refund request with a unique RefundReference.
Note that if the refund is InProgress. You may not see this error.
RefundLimitExceededThis 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.
RefundPeriodEndedRefunds 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.