Use the Session API to create and manage a Session object. The Session object represents the state of the shopper’s experience while interacting with the Drop-In. Once the shopper has completed their payment through the Drop-In, the Session will reference the created Order.
Refer to the Sessions API reference for a more technical look at each endpoint.
Note
Create a new session each time your customer attempts to pay.
Create a new session
Creating a Session is the first step to using the Reach Drop-In solution. When creating the Session, you will provide transaction details such as Items
, BillingProfile
, and Currency
, and the response will return a SessionId
. You will then use this ID to instantiate the drop-in on your browser.
Method URL
POST https://[reach_api_domain]/v<x>.<yy>/session
Request body
The request body is a session object. For required and optional fields, see the Session object. Sample requests are provided below in the Examples section or the Postman assets.
Conditional parameters
Some parameters are conditionally required depending on the country. You can find country-specific validation here. We encourage as much billing information to be passed in as possible to help process the transaction.
If you are shipping physical goods, the ShippingDetails
is required if a physical good is being shipped.
Best practice
We recommend passing as much shipping information as possible to help process the transaction.
You can provide the customer's billing address by passing one of the following options at the root level of the request:
BillingProfile
: The full object. Note that this may include aBillingProfileReference
field within this object that allows you to refer to this reference in the future.BillingProfileReference
: A free-text reference you supplied for an existing Billing Profile.BillingProfileId
: A Reach-generated ID that refers to a previously generated Billing Profile.
Response status
201 Created
Response body
See the Session object for more information.
Examples
Minimal request
This request contains only the required fields. The BillingProfile object includes the billing information.
# Location
POST https://api.withreach.com/v<x>.<yy>/session
#Headers
Authorization: Basic YWNjb3VudDpzZWNyZXQ=
Content-Type: application/json
#Body
{
"MerchantReference": "unique_reference_provided_by_merchant",
"Currency": "USD",
"Items": [
{
"Name": "Item 1",
"Amount": 10.00,
"Quantity": 1
}
],
"BillingProfile": {
"Name": "First Last",
"Email": "[email protected]",
"Address": {
"Street": "123 Street",
"City": "City",
"Country": "ES",
"Phone": "4031234567"
}
},
"AutoCapture": true,
"CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
"CancelUrl": "https://www.send-user-here-after-failed-redirect.com"
}
#Headers
Content-Type: application/json
#Body
{
"SessionId": "91b64778-0d37-479c-ae9f-32f6685ac6ea",
"State": "CREATED",
"MerchantReference": "unique_reference_provided_by_merchant",
"Items": [
{
"Name": "Item 1",
"Amount": 10.00,
"Quantity": 1
}
],
"Currency": "USD",
"TotalAmount": 10.00,
"BillingProfile": {
"BillingProfileId": "0db0dbcf-ce19-419d-980f-948cde532f44",
"Name": "First Last",
"Email": "[email protected]",
"Address": {
"Street": "123 Street",
"City": "City",
"Country": "DE",
"Phone": "4031234567"
}
}
"AutoCapture": true,
"CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
"CancelUrl": "https://www.send-user-here-after-failed-redirect.com",
"ViaAgent": false
}
Full request
This request contains all optional fields. Billing data is passed as the BillingProfile object, so note that the 'BillingProfileId' and 'BillingProfileReference' are not provided here.
# Location
POST https://api.withreach.com/v<x>.<yy>/session
#Headers
Authorization: Basic YWNjb3VudDpzZWNyZXQ=
Content-Type: application/json
#Body
{
"MerchantReference": "unique_reference_provided_by_merchant",
"Currency": "USD",
"Items": [
{
"Name": "Item 1",
"Amount": 10.00,
"Quantity": 1
},
{
"Name": "Item 2",
"Amount": 12.00,
"Quantity": 2
}
],
"BillingProfile": {
"BillingProfileReference": "MerchantSupplied-reference",
"Name": "First Last",
"Email": "[email protected]",
"Birthdate": "1980-01-02",
"Company": "Umbrella Corp",
"NationalIdentifier": "43.236.560/0001-52",
"Address": {
"Street": "123 Street",
"City": "City",
"Region": "SC",
"Country": "BR",
"Postcode": "12345678",
"Phone": "4031234567"
}
},
"ShippingDetails": {
"ShippingAmount": 0.00,
"DutyAmount": 0.00,
"Name": "First Last",
"Email": "[email protected]",
"Phone": "4031231234",
"Address": {
"Street": "123 Sreet",
"City": "City",
"Region": "AB",
"Country": "CA",
"Postcode": "X0X0X0"
}
},
"Discounts": [
{
"Name": "Discount 1",
"Amount": 2.00
},
{
"Name": "Discount 2",
"Amount": 3.00
}
],
"TaxAmount": 1.00,
"AutoCapture": true,
"CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
"CancelUrl": "https://www.send-user-here-after-failed-redirect.com",
"ViaAgent": false,
"AllowContract": true,
"OpenContract": false
}
#Headers
Content-Type: application/json
#Body
{
"SessionId": "91b64778-0d37-479c-ae9f-32f6685ac6ea",
"State": "CREATED",
"MerchantReference": "unique_reference_provided_by_merchant",
"Items": [
{
"Name": "Item 1",
"Amount": 10.0,
"Quantity": 1
},
{
"Name": "Item 2",
"Amount": 12.0,
"Quantity": 2
}
],
"Currency": "USD",
"TotalAmount": 30.0,
"BillingProfile": {
"BillingProfileId": "da7e625b-1d6d-4693-9708-e7bdbcb35df3",
"BillingProfileReference": "MerchantSupplied-reference",
"Name": "First Last",
"Email": "[email protected]",
"NationalIdentifier": "43.236.560/0001-52",
"Birthdate": "1980-01-02",
"Company": "Umbrella Corp",
"Address": {
"Street": "123 Street",
"City": "City",
"Region": "SC",
"Country": "BR",
"Postcode": "12345678"
}
},
"ShippingDetails": {
"Name": "First Last",
"Email": "[email protected]",
"Address": {
"Street": "123 Sreet",
"City": "City",
"Region": "AB",
"Country": "CA",
"Postcode": "X0X0X0"
},
"Phone": "4031231234",
"ShippingAmount": 0.0,
"DutyAmount": 0.0
},
"Discounts": [
{
"Name": "Discount 1",
"Amount": 2.0
},
{
"Name": "Discount 2",
"Amount": 3.0
}
],
"TaxAmount": 1.0,
"AutoCapture": true,
"CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
"CancelUrl": "https://www.send-user-here-after-failed-redirect.com",
"ViaAgent": false,
"AllowContract": true,
"OpenContract": false
}
Using the billing profile reference
This request is similar to the minimal request. However, the billing details are passed in using the BillingProfileReference
. This request assumes that a previous session has been created with the BillingProfileReference
supplied as MerchantSupplied-reference
(see the full request for an example). You can verify that the billing profile in the response matches a previously supplied billing profile.
This is similar to the example using the billing profile ID. However, the distinction is that you supplied the BillingProfileReference
field in a previous request, whereas Reach generated and supplied the BillingProfileId
value in a response. See The billing profile reference for more information.
# Location
POST https://api.withreach.com/v<x>.<yy>/session
#Headers
Authorization: Basic YWNjb3VudDpzZWNyZXQ=
Content-Type: application/json
#Body
{
"MerchantReference": "unique_reference_provided_by_merchant",
"Currency": "USD",
"Items": [
{
"Name": "Item 1",
"Amount": 10.00,
"Quantity": 1
}
],
"BillingProfileReference": "MerchantSupplied-reference",
"AutoCapture": true,
"CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
"CancelUrl": "https://www.send-user-here-after-failed-redirect.com"
}
#Headers
Content-Type: application/json
#Body
{
"SessionId": "88907fca-ffbd-49e6-9f15-df0ed0d2b51a",
"State": "CREATED",
"MerchantReference": "verify_docs_3",
"Items": [
{
"Name": "Item 1",
"Amount": 10.0,
"Quantity": 1
}
],
"Currency": "USD",
"TotalAmount": 10.0,
"BillingProfile": {
"BillingProfileId": "da7e625b-1d6d-4693-9708-e7bdbcb35df3",
"BillingProfileReference": "MerchantSupplied-reference",
"Name": "First Last",
"Email": "[email protected]",
"NationalIdentifier": "43.236.560/0001-52",
"Birthdate": "1980-01-02",
"Company": "Umbrella corp",
"Address": {
"Street": "123 Sreet",
"City": "City",
"Region": "SC",
"Country": "BR",
"Postcode": "12345678"
}
},
"AutoCapture": true,
"CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
"CancelUrl": "https://www.send-user-here-after-failed-redirect.com",
"ViaAgent": false
Using the billing profile ID
This request is similar to the minimal request. However, the request passed billing data using the BillingProfileId
. The ID matches a previously supplied BillingProfileId
from a response, so a session must have been successfully created with the corresponding BillingProfileId
first.
This request resembles the example using the billing profile reference. However, the distinction is that you supplied the BillingProfileReference
field in a previous request, whereas Reach generated and supplied the BillingProfileId
value in a response. See The billing profile ID for more information.
# Location
POST https://api.withreach.com/v<x>.<yy>/session
#Headers
Authorization: Basic YWNjb3VudDpzZWNyZXQ=
Content-Type: application/json
#Body
{
"MerchantReference": "unique_reference_provided_by_merchant",
"Currency": "USD",
"Items": [
{
"Name": "Item 1",
"Amount": 10.00,
"Quantity": 1
}
],
"BillingProfileId": "da7e625b-1d6d-4693-9708-e7bdbcb35df3",
"AutoCapture": true,
"CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
"CancelUrl": "https://www.send-user-here-after-failed-redirect.com"
}
#Headers
Content-Type: application/json
#Body
{
"SessionId": "88907fca-ffbd-49e6-9f15-df0ed0d2b51a",
"State": "CREATED",
"MerchantReference": "verify_docs_3",
"Items": [
{
"Name": "Item 1",
"Amount": 10.0,
"Quantity": 1
}
],
"Currency": "USD",
"TotalAmount": 10.0,
"BillingProfile": {
"BillingProfileId": "da7e625b-1d6d-4693-9708-e7bdbcb35df3",
"BillingProfileReference": "MerchantSupplied-reference",
"Name": "First Last",
"Email": "[email protected]",
"NationalIdentifier": "43.236.560/0001-52",
"Birthdate": "1980-01-02",
"Company": "Umbrella corp",
"Address": {
"Street": "123 Sreet",
"City": "City",
"Region": "SC",
"Country": "BR",
"Postcode": "12345678"
}
},
"AutoCapture": true,
"CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
"CancelUrl": "https://www.send-user-here-after-failed-redirect.com",
"ViaAgent": false
Errors
See the Error Object for more information.
HttpStatus | Code | Message | FieldErrors |
---|---|---|---|
400 | INVALID_REQUEST | Invalid request syntax | Yes |
400 | INVALID_CURRENCY | Provided currency is not supported | No |
401 | AUTHENTICATION_REQUIRED | Username/password must be supplied to access this resource | No |
401 | AUTHENTICATION_REQUIRED | Supplied username/password are invalid | No |
403 | NOT_AUTHORIZED | User is not permitted to access this resource | No |
409 | DUPLICATE_MERCHANT_REFERENCE_ID | Session with merchant reference already exists | No |
415 | UNSUPPORTED_MEDIA_TYPE | Expected content-type: application/json | No |
500 | INTERNAL_SERVER_ERROR | The server could not process the request due to an unexpected error | No |
Retrieve a session
A Session can be retrieved using the SessionId
. The response returns the current state of the Session..
Method URL
GET https://[reach_api_domain]/v<x>.<yy>/session/{SessionId}
Path Parameter
Parameter | Description |
---|---|
SessionId | Unique identifier for the Session object. |
Response status
200 OK
Response body
See the Session object for more information.
Errors
See the Error Object for more information.
HttpStatus | Code | Message | FieldErrors |
---|---|---|---|
400 | VALIDATION_ERROR | Not a valid UUID | No |
401 | AUTHENTICATION_REQUIRED | Username/password must be supplied to access this resource | No |
401 | AUTHENTICATION_REQUIRED | Supplied username/password are invalid | No |
403 | NOT_AUTHORIZED | User is not permitted to access this resource | No |
404 | SESSION_NOT_FOUND | No session exists for session ID {SessionId} | No |
500 | INTERNAL_SERVER_ERROR | The server could not process the request due to an unexpected error | No |
Cancel a non-final session
You cannot cancel a Session if it is still in the initial state of CREATED. Canceling a Session in any other state will result in an error.
Method URL
DELETE https://[reach_api_domain]/v<x>.<yy>/session/{SessionId}
Path parameter
Parameter | Description |
---|---|
SessionId | The unique identifier for the Session object. |
Response status
204 No Content
Response body
null
Errors
See the Error Object for more information.
HttpStatus | Code | Message | FieldErrors |
---|---|---|---|
400 | VALIDATION_ERROR | Not a valid UUID | No |
401 | AUTHENTICATION_REQUIRED | Username/password must be supplied to access this resource | No |
401 | AUTHENTICATION_REQUIRED | Supplied username/password are invalid | No |
403 | NOT_AUTHORIZED | User is not permitted to access this resource | No |
404 | SESSION_NOT_FOUND | No session exists for session ID {SessionId} | No |
409 | INVALID_SESSION_STATE | Session cannot be CANCELLED as it is already COMPLETED | No |
500 | INTERNAL_SERVER_ERROR | The server could not process the request due to an unexpected error | No |
Update a session
You cannot update a Session if it is still in the initial state of CREATED. Updating a Session in any other state will result in an error. The update request acts as a replacement for the Session object found on the server. The request must pass all requirements to replace the existing Session object.
Method URL
PUT https://[reach_api_domain]/v<x>.<yy>/session/{SessionId}
Path parameter
Parameter | Description |
---|---|
SessionId | Unique identifier for the Session object. |
Request body
The request body is a session object. See the Session object for information on required and optional fields. Sample requests are provided below in the Examples section or the Postman assets.
Examples
The following examples assume you created a session using the full request from the Create a new session examples.
#Headers
Content-Type: application/json
#Body
{
"SessionId": "91b64778-0d37-479c-ae9f-32f6685ac6ea",
"State": "CREATED",
"MerchantReference": "unique_reference_provided_by_merchant",
"Items": [
{
"Name": "Item 1",
"Amount": 10.0,
"Quantity": 1
},
{
"Name": "Item 2",
"Amount": 12.0,
"Quantity": 2
}
],
"Currency": "USD",
"TotalAmount": 30.0,
"BillingProfile": {
"BillingProfileId": "da7e625b-1d6d-4693-9708-e7bdbcb35df3",
"BillingProfileReference": "MerchantSupplied-reference",
"Name": "First Last",
"Email": "[email protected]",
"NationalIdentifier": "43.236.560/0001-52",
"Birthdate": "1980-01-02",
"Company": "Umbrella Corp",
"Address": {
"Street": "123 Street",
"City": "City",
"Region": "SC",
"Country": "BR",
"Postcode": "12345678"
}
},
"ShippingDetails": {
"Name": "First Last",
"Email": "[email protected]",
"Address": {
"Street": "123 Sreet",
"City": "City",
"Region": "AB",
"Country": "CA",
"Postcode": "X0X0X0"
},
"Phone": "4031231234",
"ShippingAmount": 0.0,
"DutyAmount": 0.0
},
"TaxAmount": 1.0,
"AutoCapture": true,
"CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
"CancelUrl": "https://www.send-user-here-after-failed-redirect.com",
"ViaAgent": false,
"Discounts": [
{
"Name": "Discount 1",
"Amount": 2.0
},
{
"Name": "Discount 2",
"Amount": 3.0
}
]
}
Full update
This request updates all the fields in the session. Since we replaced everything, including the items, the object passed in must fully represent the new session.
# Location
PUT https://api.withreach.com/v<x>.<yy>/session/91b64778-0d37-479c-ae9f-32f6685ac6ea
#Headers
Authorization: Basic YWNjb3VudDpzZWNyZXQ=
Content-Type: application/json
#Body
{
"MerchantReference": "NewReference",
"Currency": "CAD",
"Items": [
{
"Name": "new Item",
"Amount": 15.00,
"Quantity": 1
}
],
"BillingProfile": {
"BillingProfileReference": "MerchantSupplied-reference-new",
"Name": "new name",
"Email": "[email protected]",
"Birthdate": "1990-01-02",
"Company": "New corp",
"Address": {
"Street": "123 Sreet",
"City": "City",
"Region": "AB",
"Country": "CA",
"Postcode": "H0H0H0",
"Phone": "4031234567"
}
},
"ShippingDetails": {
"ShippingAmount": 1.00,
"DutyAmount": 2.00,
"Name": "First Last",
"Email": "[email protected]",
"Phone": "4031231234",
"Address": {
"Street": "123 Sreet",
"City": "City",
"Region": "AB",
"Country": "CA",
"Postcode": "H0H0H0"
}
},
"Discounts": [
{
"Name": "Discount 1",
"Amount": 2.00
}
],
"TaxAmount": 2.00,
"AutoCapture": false,
"CompleteUrl": "https://www.new-success-url.com",
"CancelUrl": "https://www.new-failure-url.com",
"ViaAgent": true,
"AllowContract": true,
"OpenContract": false
#Headers
Content-Type: application/json
#Body
{
"SessionId": "91b64778-0d37-479c-ae9f-32f6685ac6ea",
"State": "CREATED",
"MerchantReference": "NewReference",
"Items": [
{
"Name": "new Item",
"Amount": 15.0,
"Quantity": 1
}
],
"Currency": "CAD",
"TotalAmount": 18.0,
"BillingProfile": {
"BillingProfileId": "8d89fd08-9b37-4bd9-8b9d-d8250ee6d256",
"BillingProfileReference": "MerchantSupplied-reference-new",
"Name": "new name",
"Email": "[email protected]",
"Birthdate": "1990-01-02",
"Company": "New corp",
"Address": {
"Street": "123 Sreet",
"City": "City",
"Region": "AB",
"Country": "CA",
"Postcode": "H0H0H0"
}
},
"ShippingDetails": {
"Name": "First Last",
"Email": "[email protected]",
"Address": {
"Street": "123 Sreet",
"City": "City",
"Region": "AB",
"Country": "CA",
"Postcode": "H0H0H0"
},
"Phone": "4031231234",
"ShippingAmount": 1.0,
"DutyAmount": 2.0
},
"Discounts": [
{
"Name": "Discount 1",
"Amount": 2.0
}
],
"TaxAmount": 2.0,
"AutoCapture": false,
"CompleteUrl": "https://www.new-success-url.com",
"CancelUrl": "https://www.new-failure-url.com",
"ViaAgent": false,
"AllowContract": true,
"OpenContract": false
}
Conditional parameters
Some parameters are conditionally required depending on the country. You can find country-specific validation here. We encourage as much billing information to be passed in as possible to help process the transaction.
The ShippingDetails
is required if a physical good is being shipped. We encourage as much shipping information to be passed in as possible to help process the transaction.
The customer billing address may be passed in by passing a single one of the following at the root level of the request:
BillingProfile
- The full BillingProfile object. Note that this may include a
BillingProfileReference
within this object, a field that can be defined to refer to this reference in the future.BillingProfileReference
- a free-text reference you supplied for an existing Billing Profile.BillingProfileId
- a Reach-generated ID that refers to a previously generated Billing Profile.
Response status
200 OK
Response body
See the Session object for more information.
Errors
See Error object for more information.
HttpStatus | Code | Message | FieldErrors |
---|---|---|---|
400 | INVALID_REQUEST | Invalid request syntax | Yes |
400 | INVALID_CURRENCY | Provided currency is not supported | No |
400 | VALIDATION_ERROR | Not a valid UUID | No |
401 | AUTHENTICATION_REQUIRED | Username/password must be supplied to access this resource | No |
401 | AUTHENTICATION_REQUIRED | Supplied username/password are invalid | No |
403 | NOT_AUTHORIZED | User is not permitted to access this resource | No |
404 | SESSION_NOT_FOUND | No session exists for session ID {SessionId} | No |
409 | DUPLICATE_MERCHANT_REFERENCE_ID | Session with merchant reference already exists | No |
409 | DUPLICATE_REQUEST | A request with this ID is currently in progress | No |
415 | UNSUPPORTED_MEDIA_TYPE | Expected content-type: application/json | No |
500 | INTERNAL_SERVER_ERROR | The server could not process the request due to an unexpected error | No |
Objects
The following section outlines the Session API's HTTP request and response objects. For usage of these objects, see the following topics for details on how they are implemented with the calls.
- Session object
- Item object
- BillingProfile object
- ShippingDetails object
- Address object
- Discount object
- Order object
- BankDetails object
- Error object
- FieldError object
Session object
Note that "Required" fields refer to the request. The column "Returned when" describes the conditions under which a field is returned—assume the field is not present in the request if these conditions aren't met.
Attributes | Type | Required? | In Request? | Returned When | Description |
---|---|---|---|---|---|
MerchantReference | String | Yes | Yes | Always | Free-text unique identifier supplied by the caller. |
AutoCapture | Boolean | Yes | Yes | Always | Use an indicator to determine if an Order will be auto-captured after authorization. |
CompleteUrl | String | Yes | Yes | Always | The URL the customer will be directed to if a redirect is completed successfully. |
CancelUrl | String | Yes | Yes | Always | This is the URL the customer will be directed to if a redirect fails or is cancelled. It should return the user to the page with the Drop-In so the user can try again. |
Currency | Enum | Yes | Yes | Always | The three-letter ISO-4217 currency code is used to process the payment. |
Items | List of Items | Yes | Yes | Always | The supplied list of Item objects to be paid. At least one Item must be supplied. |
BillingProfile | BillingProfile | Yes* | Yes* | Always | Billing information for a customer. |
BillingProfileReference | String | Yes* | Yes* | When supplied in a request | Unique merchant-supplied billing profile reference |
BillingProfileId | UUID | Yes* | Yes* | Always | Reach-generated ID for an existing billing profile |
ViaAgent | Boolean | No | Yes | Always | This indicates that an agent is creating this session, not the end consumer. If false or absent, the Session is assumed to be placed by the end consumer. |
ShippingDetails | ShippingDetails | No | Yes | When supplied in a request | Shipping information for a customer. |
TaxAmount | Number | No | Yes | When supplied in a request | The tax amount for the order. Will be added to the TotalAmount. |
Discounts | List of Discount | No | Yes | When supplied in a request | List of discounts to be applied against the session. Each discount will be subtracted from the TotalAmount. |
SessionId | UUID | No | No | Always | Unique identifier for the object. Used to pass to the Drop-In. |
State | Enum | No | No | Always | Current state of the object. See the Session State Enum section below for more. |
TotalAmount | Number | No | No | Always | Sum of TaxAmount , ShippingDetails .ShippingAmount , ShippingDetails.DutyAmount and all Item.Amounts , minus any Discounts . |
Order | Order | No | No | When state is COMPLETED | Created Order after the user has completed the Drop-In for the Session. |
AllowContract | Boolean | No | Yes | When supplied in a request | Permit users to create a contract (used for recurring billing, subscriptions, stored payment options, etc.) when submitting their payment. |
OpenContract | Boolean | No | Yes | When supplied in a request | Indicates that the payment is intended to be used to start a subscription and will, if successful, create a contract |
* One of BillingProfile
, BillingProfileReference
, or BillingProfileId
is required at the root level of the request. If BillingProfile
is supplied, a new billing profile is created. Otherwise, BillingProfileReference
or BillingProfileId
must refer to an existing billing profile.
Item object
Items represent charges against the user, such as goods in a shopping cart. They can be provided individually in the request to allow a breakdown of the session charges to be shown.
Attributes | Type | Required? | Description |
---|---|---|---|
Name | String | Yes | Supplied the name of the item to be paid. |
Amount | Number | Yes | Supplied the amount of the item to be paid. The parent object defines currency. |
Quantity | Integer | Yes | Supplied the number of the item to be paid. |
BillingProfile object
The BillingProfile
includes the user's billing information that may be passed on to a processor.
Attributes | Type | Required? | Supplied in request? | Description |
---|---|---|---|---|
BillingProfileId | UUID | No | No | Reach-generated identifier |
BillingProfileReference | String | No | Yes | Unique merchant-supplied identifier. This is a free-text field. |
Name | String | Yes | Yes | Billing full name. |
String | Yes | Yes | Billing email address. | |
Phone | String | No | Yes | Billing phone number. |
BirthDate | String | Yes, for Brazil (BR). See Country Specific Fields | Yes | Billing birthdate (format yyyy-MM-dd). |
NationalIdentifier | String | Yes, For Brazil, Argentina or India (BR, AR, IN). See Country Specific Fields | Yes | Billing national ID, such as SSN or CPF. |
Company | String | Yes, for a request with a Brazilian CNPJ. See Country Specific Fields | Yes | Billing profile company |
Address | Address | Yes | Yes | Billing address. |
ShippingDetails object
The ShippingDetails
represent the destination to send goods, and are applicable only for physical goods.
Attributes | Type | Required? | Description |
---|---|---|---|
ShippingAmount | Number | Yes | Charges for shipping, not including taxes and duties. |
DutyAmount | Number | Yes | Duty charged for the order. |
Name | String | Yes | Shipping full name. |
String | Yes | Shipping email address. | |
Phone | String | Yes | Shipping phone number. |
Address | Address | Yes | Shipping address. |
Address object
Attributes | Type | Required? | Description |
---|---|---|---|
Street | String | Yes | Customer's street address. |
City | String | Yes | Customer's city. |
Region | String | Yes, for Canada, Mexico, United States (CA, MX, US). See Country Specific Fields | Customer's state or province (ISO-3166-2 subdivision code). |
Country | String | Yes | Customer's country (upper-case ISO 3166 alpha-2 country code). |
Postcode | String | Yes, for Brazil, Canada, Mexico, and the United States (BR, CA, MX, US). See Country Specific Fields | Customer's zip/postal code. |
Discount object
Attributes | Type | Required? | Description |
---|---|---|---|
Name | String | Yes | A free-text field describing the discount |
Amount | Number | Yes | Flat amount of the discount. This will be subtracted from the TotalAmount. If this puts the TotalAmount in the negative, an error will be returned |
Order object
An order is created once a session is complete. Note that orders will not appear in any requests.
Attributes | Type | Returned when? | Description |
---|---|---|---|
OrderId | UUID | Always | Unique identifier for the object. |
State | Enum | Always | Current state of the object. |
MerchantReference | String | Always | Unique identifier supplied. Will match the Session.MerchantReference . |
SessionId | UUID | Always | Unique identifier for the Session object. |
BankDetails | BankDetails | Payment method was Bank Transfer | Details needed for the user to complete a bank transfer. |
BankDetails object
The BankDetails
are provided only when a user pays via Bank Transfer and will only be included in Session responses.
Attributes | Type | Description |
---|---|---|
AccountHolder | String | The name of the receiving account holder, if available. |
AccountNumber | String | The account number receiving the payment. |
BankName | String | The name of the bank receiving the payment. |
City | String | City of the processing bank. |
Country | String | Country of the processing bank. |
Iban | String | International Bank Account Number. |
PaymentReference | String | The merchant order number. |
SwiftCode | String | The unique bank identifier. |
ExtraBankData | String | Country-specific bank information (eg, ABA) |
Error object
Any 4xx or 5xx level error will return a consistently formatted error object.
Attributes | Type | Returned when? | Description |
---|---|---|---|
Code | String | Always | Identifying the code of a presented error. |
Message | String | Always | Human-readable details of a presented error. |
FieldErrors | List of FieldError | When a field-level validation occurs | A list of FieldError objects. |
Error objects will look like the following:
{
"Code": "SOME_CODE",
"Message": "SOME_MESSAGE",
"FieldErrors": [
{
"Field": "SOME_FIELD",
"Code": "SOME_CODE",
"Message": "SOME_MESSAGE"
}
]
}
The Code
is intended to be consumed programmatically. Expect only alphanumeric characters and underscores.
The Message
field is human-readable and may contain whitespace and/or special characters. It is intended to assist debugging and should not be used for logic.
The FieldErrors
parameters is optional and will only be present for applicable errors.
FieldError object
Field errors are returned when a specific field in a request contains a validation error, such as an invalid format or a value that does not match an enum.
Attributes | Type | Description |
---|---|---|
Field | String | Field associated with the error. |
Code | String | Identifying the code of a presented field error. |
Message | String | Human-readable details of a presented field error. |
Enums
This section outlines the various restricted-value enums. Requests that do not match these enums will throw
a field-level error.
Currency
Value | Description |
---|---|
USD | United States dollar |
EUR | Euro |
CAD | Canadian dollar |
GBP | Pound |
AUD | Australian dollar |
BRL | Brazilian real |
JPY | Japanese yen |
MXN | Mexican peso |
CHF | Swiss franc |
SGD | Singapore dollar |
ILS | Israeli new shekel |
NZD | New Zealand dollar |
HKD | Hong Kong dollar |
AED | United Arab Emirates dirham |
SEK | Swedish Krona |
SAR | Saudi riyal |
DKK | Danish krone |
NOK | Norwegian krone |
RUB | Russian ruble |
MYR | Malaysian ringgit |
PHP | Philippine peso |
THB | Thai baht |
KRW | South Korean won |
INR | Indian rupee |
CLP | Chilean peso |
PLN | Polish złoty |
TWD | New Taiwan dollar |
TRY | Turkish lira |
CZK | Czech koruna |
KWD | Kuwaiti dinar |
QAR | Qatari riyal |
ZAR | South African rand |
HUF | Hungarian forint |
RON | Romanian leu |
PEN | Peruvian sol |
IDR | Indonesian rupiah |
CNY | Renminbi |
EGP | Egyptian pound |
ARS | Argentine peso |
COP | Colombian peso |
ISK | Icelandic krona |
UAH | Ukrainian hryvnia |
HRK | Croatian kuna |
BND | Brunei dollar |
BHD | Bahraini dinar |
CRC | Costa Rican colón |
PKR | Pakistani rupee |
BGN | Bulgarian lev |
VND | Vietnamese dong |
LKR | Sri Lankan rupee |
MOP | Macanese pataca |
MAD | Moroccan dirham |
GTQ | Guatemalan quetzal |
BMD | Bermudian dollar |
OMR | Omani rial |
RSD | Serbian dinar |
DOP | Dominican peso |
PAB | Panamanian balboa |
LBP | Lebanese pound |
TTD | Trinidad and Tobago Dollar |
Session state
Value | Final State? | Description |
---|---|---|
CREATED | No | The session was initiated using the Create Session endpoint. A shopper may attempt payment using the Drop-In. |
PROCESSING | No* | A short-lived state signifying a payment attempt is being processed. |
REDIRECTED | No | This state indicates Drop-In redirected the shopper to the payment provider to complete the payment. |
COMPLETED | Yes | This final state signifies that the user has completed interacting with the Drop-In and Drop-In has created an order. |
CANCELLED | Yes | This final state indicates a merchant has requested the cancellation of a CREATED Session. |
FAILED | Yes | This final state signifies that something has gone wrong while the user tried completing the payment. |
*PROCESSING transactions will transition to another state automatically without user input
Order state
Description | |
---|---|
Processing | A payment attempt requiring external action (e.g., Bank Transfer). |
PaymentAuthorized | The payment provider authorized the payment. If the order is not under review, payment capture may proceed. |
Processed | Payment for the order has completed successfully. |
ProcessingFailed | The last payment attempt for the order was not successful. |
Cancelled | The merchant canceled the order explicitly, or the order expired before being captured. |
Declined | Reach declined the order as a result of a manual fraud review. |