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 a BillingProfileReference 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

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.
Email	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.
Email	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.

📘Note

Create a new session

Method URL

Request body

Conditional parameters

👍Best practice

Response status

Response body

Examples

Minimal request

Full request

Using the billing profile reference

Using the billing profile ID

Errors

Retrieve a session

Method URL

Path Parameter

Response status

Response body

Errors

Cancel a non-final session

Method URL

Path parameter

Response status

Response body

Errors

Update a session

Method URL

Path parameter

Request body

Examples

Full update

Conditional parameters

Response status

Response body

Errors

Objects

Session object

Item object

BillingProfile object

ShippingDetails object

Address object

Discount object

Order object

BankDetails object

Error object

FieldError object

Enums

Currency

Session state

Order state

📘
Note

👍
Best practice