Overview

The Session API is used 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 successfully completed their payment through the Drop-In, the Session will contain a reference to the Order that was created.

For a more technical look at each endpoint you can also refer to the Reach Session API Reference.

📘
A new session should be created each time your customer attempts to pay.

Usage

Create Session

Creating a Session is the first step to using the Reach Drop-In solution. When creating the Session you will provide various transaction details such as Items, BillingProfile, and Currency. Once a Session is created, you will be returned a SessionId. This ID is what you will then use to instantiate the Drop-In on your client's browser.

Method

POST

Path

v1/session

Request Body

The request body is a session object. See the section under Session object for required and option fields. Sample requests are provided below in the Examples section, or in the Postman assets.

Conditional parameters

Some parameters are conditionally required depending on the country. Country specific validation can be found 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 you may define 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

Session Object

Examples

Minimal Request

This request contains only the required fields. The billing information is passed in as a BillingProfile.

Request

    # Location
    POST https://api.withreach.com/v1/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"
    }

Response

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

Request

    # Location
    POST https://api.withreach.com/v1/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 Sreet",
                "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
    }

Response

    #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 Sreet",
                "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 important distinction is that the BillingProfileReference is a field that you supplied in a previous request, whereas the BillingProfileId is a value that Reach generated and supplied in a response.

Request

    # Location
    POST https://api.withreach.com/v1/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"
    }

Response

    #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 billing data is passed in using the BillingProfileId. This matches a previously supplied BillingProfileId from a response, so a session must have been successfully created with the corresponding BillingProfileId first.

This is similar to the example using the billing profile reference, however the important distinction is that the BillingProfileReference is a field that you supplied in a previous request, whereas the BillingProfileId is a value that Reach generated and supplied in a response.

Request

    # Location
    POST https://api.withreach.com/v1/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"
    }

Response

    #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

Error Object

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 Session

A Session can be retrieved using the SessionId. The current state of the Session will be returned.

Method

GET

Path

v1/session/{SessionId}

Path Parameter

Parameter	Description
SessionId	Unique identifier for the Session object.

Response Status

200 OK

Response Body

Session Object

Errors

Error Object

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 Session

A Session can be cancelled if it is still in the initial state of CREATED. Trying to cancel a Session in any other state will result in an error.

Method

DELETE

Path

v1/session/{SessionId}

Path Parameter

Parameter	Description
SessionId	Unique identifier for the Session object.

Response Status

204 No Content

Response Body

null

Errors

Error Object

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 Session

A Session can be updated if it is still in the initial state of CREATED. Trying to update a Session in any other state will result in an error. The update request acts as a replacement of the Session object found on the server. The request passed in must pass all requirements to replace the existing Session object.

Method

PUT

Path

v1/session/{SessionId}

Path Parameter

Parameter	Description
SessionId	Unique identifier for the Session object.

Request Body

The request body is a session object. See the section under Session object for required and option fields. Sample requests are provided below in the Examples section, or in the Postman assets.

Examples

The following examples assume that a session has already been created using the full request from the session creation examples. The created session is also provided here:

Response

    #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 Sreet",
                "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. Note that everything is replaced, including the items, so the object passed in must be a full representation of the new session.

Request

    # Location
    PUT https://api.withreach.com/v1/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

Response

    #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

Session Object

Errors

Error Object

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 HTTP request and response objects for the Session API. For usage of these objects, please see the individual section under Usage for details one how they are implemented with the calls.

Session

Please note that "Required" fields refer to the request.The column "Returned when" describes the conditions where 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 caller.
AutoCapture	Boolean	Yes	Yes	Always	Indicator used 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	The URL the customer will be directed to if a redirect is failed or cancelled. This should return the user to the page with the Drop-In so the user can try again.
Currency	Enum	Yes	Yes	Always	Three-letter ISO-4217 currency code used to process the payment.
Items	List of Items	Yes	Yes	Always	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 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	Indicates that this Session is being made by an agent, and not the end consumer. If false or not present, the Session is assumed to be placed by the end consumer.
ShippingDetails	ShippingDetails	No	Yes	When supplied in request	Shipping information for a customer.
TaxAmount	Number	No	Yes	When supplied in request	The tax being charged. Will be added to the TotalAmount.
Discounts	List of Discount	No	Yes	When supplied in 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 user has completed the Drop-In for the Session.
AllowContract	Boolean	No	Yes	When supplied in request	Permit user creation of a contract (used for recurring billing, subscriptions, stored payment options, etc.) when submitting their payment.
OpenContract	Boolean	No	Yes	When supplied in 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

Items represent charges against the user, such as goods in a shopping cart. They can be provided on an individual basis in the request to allow a breakdown of the session charges to be shown.

Attributes	Type	Required ?	Description
Name	String	Yes	Supplied name of item to be paid.
Amount	Number	Yes	Supplied amount of item to be paid. Currency is defined by parent object.
Quantity	Integer	Yes	Supplied quantity of the item to be paid.

BillingProfile

The BillingProfile is 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 request with a Brazilian CNPJ. See Country Specific Fields	Yes	Billing profile company
Address	Address	Yes	Yes	Billing address.

ShippingDetails

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

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, United States (BR, CA, MX, US). See Country Specific Fields	Customer's zip/postal code.

Discount

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

An Order is created when a session is completed. Please note that orders will not be present 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 user to complete a bank transfer.

Bank Details

BankDetails are returned only when a user is paying by Bank Transfer. These will only be returned 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 processing bank.
Country	String	Country of 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 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 for assisting with 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 code of a presented field error.
Message	String	Human-readable details of a presented field error.

Enums

This section will outline 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	Session has been initiated using the Create Session endpoint. A payment may be attempted using the Drop-In.
PROCESSING	No*	Short lived state signifying a payment attempt is being processed.
REDIRECTED	No	State that resembles a user has been redirected away from the Drop-In to complete the payment.
COMPLETED	Yes	Final state signifying the user has completed interacting with the Drop-In and an order was created.
CANCELLED	Yes	Final state after a merchant has requested a cancellation of a CREATED Session.
FAILED	Yes	Final state signifying something has gone wrong while the user tried completing the payment.

*PROCESSING transactions will transition to another state automatically without user input

Order State

Value	Description
Processing	A payment attempt requiring external action (e.g. Bank Transfer).
PaymentAuthorized	Payment has been authorized. If the order is not under review payment capture may proceed.
Processed	Payment for the order has completed successfully.
ProcessingFailed	The last payment attempt made for the order was not successful.
Cancelled	The order was cancelled explicitly by the merchant or the order expired before being captured.
Declined	The order was declined as a result of a manual fraud review.