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

HttpStatusCodeMessageFieldErrors
400INVALID_REQUESTInvalid request syntaxYes
400INVALID_CURRENCYProvided currency is not supportedNo
401AUTHENTICATION_REQUIREDUsername/password must be supplied to access this resourceNo
401AUTHENTICATION_REQUIREDSupplied username/password are invalidNo
403NOT_AUTHORIZEDUser is not permitted to access this resourceNo
409DUPLICATE_MERCHANT_REFERENCE_IDSession with merchant reference already existsNo
415UNSUPPORTED_MEDIA_TYPEExpected content-type: application/jsonNo
500INTERNAL_SERVER_ERRORThe server could not process the request due to an unexpected errorNo

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

ParameterDescription
SessionIdUnique identifier for the Session object.

Response Status

200 OK

Response Body

Session Object

Errors

Error Object

HttpStatusCodeMessageFieldErrors
400VALIDATION_ERRORNot a valid UUIDNo
401AUTHENTICATION_REQUIREDUsername/password must be supplied to access this resourceNo
401AUTHENTICATION_REQUIREDSupplied username/password are invalidNo
403NOT_AUTHORIZEDUser is not permitted to access this resourceNo
404SESSION_NOT_FOUNDNo session exists for session ID {SessionId}No
500INTERNAL_SERVER_ERRORThe server could not process the request due to an unexpected errorNo

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

ParameterDescription
SessionIdUnique identifier for the Session object.

Response Status

204 No Content

Response Body

null

Errors

Error Object

HttpStatusCodeMessageFieldErrors
400VALIDATION_ERRORNot a valid UUIDNo
401AUTHENTICATION_REQUIREDUsername/password must be supplied to access this resourceNo
401AUTHENTICATION_REQUIREDSupplied username/password are invalidNo
403NOT_AUTHORIZEDUser is not permitted to access this resourceNo
404SESSION_NOT_FOUNDNo session exists for session ID {SessionId}No
409INVALID_SESSION_STATESession cannot be CANCELLED as it is already COMPLETEDNo
500INTERNAL_SERVER_ERRORThe server could not process the request due to an unexpected errorNo

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

ParameterDescription
SessionIdUnique 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

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

HttpStatusCodeMessageFieldErrors
400INVALID_REQUESTInvalid request syntaxYes
400INVALID_CURRENCYProvided currency is not supportedNo
400VALIDATION_ERRORNot a valid UUIDNo
401AUTHENTICATION_REQUIREDUsername/password must be supplied to access this resourceNo
401AUTHENTICATION_REQUIREDSupplied username/password are invalidNo
403NOT_AUTHORIZEDUser is not permitted to access this resourceNo
404SESSION_NOT_FOUNDNo session exists for session ID {SessionId}No
409DUPLICATE_MERCHANT_REFERENCE_IDSession with merchant reference already existsNo
409DUPLICATE_REQUESTA request with this ID is currently in progressNo
415UNSUPPORTED_MEDIA_TYPEExpected content-type: application/jsonNo
500INTERNAL_SERVER_ERRORThe server could not process the request due to an unexpected errorNo

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.

AttributesTypeRequired?In Request?Returned WhenDescription
MerchantReferenceStringYesYesAlwaysFree-text unique identifier supplied by caller.
AutoCaptureBooleanYesYesAlwaysIndicator used to determine if an Order will be auto-captured after authorization.
CompleteUrlStringYesYesAlwaysThe URL the customer will be directed to if a redirect is completed successfully.
CancelUrlStringYesYesAlwaysThe 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.
CurrencyEnumYesYesAlwaysThree-letter ISO-4217 currency code used to process the payment.
ItemsList of ItemsYesYesAlwaysSupplied list of Item objects to be paid. At least one Item must be supplied.
BillingProfileBillingProfileYes*Yes*AlwaysBilling information for a customer.
BillingProfileReferenceStringYes*Yes*When supplied in requestUnique merchant-supplied billing profile reference
BillingProfileIdUUIDYes*Yes*AlwaysReach-generated ID for an existing billing profile
ViaAgentBooleanNoYesAlwaysIndicates 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.
ShippingDetailsShippingDetailsNoYesWhen supplied in requestShipping information for a customer.
TaxAmountNumberNoYesWhen supplied in requestThe tax being charged. Will be added to the TotalAmount.
DiscountsList of DiscountNoYesWhen supplied in requestList of discounts to be applied against the session. Each discount will be subtracted from the TotalAmount
SessionIdUUIDNoNoAlwaysUnique identifier for the object. Used to pass to the Drop-In.
StateEnumNoNoAlwaysCurrent state of the object. See the Session State Enum section below for more
TotalAmountNumberNoNoAlwaysSum of TaxAmount, ShippingDetails.ShippingAmount, ShippingDetails.DutyAmount and all Item.Amounts, minus any Discounts.
OrderOrderNoNoWhen state is COMPLETEDCreated Order after user has completed the Drop-In for the Session.
AllowContractBooleanNoYesWhen supplied in requestPermit user creation of a contract (used for recurring billing, subscriptions, stored payment options, etc.) when submitting their payment.
OpenContractBooleanNoYesWhen supplied in requestIndicates 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.

AttributesTypeRequired ?Description
NameStringYesSupplied name of item to be paid.
AmountNumberYesSupplied amount of item to be paid. Currency is defined by parent object.
QuantityIntegerYesSupplied quantity of the item to be paid.

BillingProfile

The BillingProfile is the user's billing information that may be passed on to a processor.

AttributesTypeRequired?Supplied in request?Description
BillingProfileIdUUIDNoNoReach-generated identifier
BillingProfileReferenceStringNoYesUnique merchant-supplied identifier. This is a free-text field.
NameStringYesYesBilling full name.
EmailStringYesYesBilling email address.
PhoneStringNoYesBilling phone number.
BirthDateStringYes, for Brazil (BR). See Country Specific FieldsYesBilling birthdate (format yyyy-MM-dd).
NationalIdentifierStringYes, For Brazil, Argentina or India (BR, AR, IN). See Country Specific FieldsYesBilling national ID, such as SSN or CPF.
CompanyStringYes, for request with a Brazilian CNPJ. See Country Specific FieldsYesBilling profile company
AddressAddressYesYesBilling address.

ShippingDetails

The ShippingDetails represent the destination to send goods, and are applicable only for physical goods.

AttributesTypeRequired ?Description
ShippingAmountNumberYesCharges for shipping not including taxes and duties.
DutyAmountNumberYesDuty charged for the order.
NameStringYesShipping full name.
EmailStringYesShipping email address.
PhoneStringYesShipping phone number.
AddressAddressYesShipping address.

Address

AttributesTypeRequired?Description
StreetStringYesCustomer's street address.
CityStringYesCustomer's city.
RegionStringYes, for Canada, Mexico, United States (CA, MX, US). See Country Specific FieldsCustomer's state or province (ISO-3166-2 subdivision code).
CountryStringYesCustomer's country (upper-case ISO 3166 alpha-2 country code).
PostcodeStringYes, for Brazil, Canada, Mexico, United States (BR, CA, MX, US). See Country Specific FieldsCustomer's zip/postal code.

Discount

AttributesTypeRequired?Description
NameStringYesA free-text field describing the discount
AmountNumberYesFlat 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.

AttributesTypeReturned when?Description
OrderIdUUIDAlwaysUnique identifier for the object.
StateEnumAlwaysCurrent state of the object.
MerchantReferenceStringAlwaysUnique identifier supplied. Will match the Session.MerchantReference.
SessionIdUUIDAlwaysUnique identifier for the Session object.
BankDetailsBankDetailsPayment method was Bank TransferDetails 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.

AttributesTypeDescription
AccountHolderStringThe name of the receiving account holder, if available.
AccountNumberStringThe account number receiving the payment.
BankNameStringThe name of the bank receiving the payment.
CityStringCity of processing bank.
CountryStringCountry of processing bank.
IbanStringInternational Bank Account Number.
PaymentReferenceStringThe merchant order number.
SwiftCodeStringThe unique bank identifier.
ExtraBankDataStringCountry-specific bank information (eg. ABA)

Error Object

Any 4xx or 5xx level error will return a consistently formatted error object.

AttributesTypeReturned when?Description
CodeStringAlwaysIdentifying code of a presented error.
MessageStringAlwaysHuman-readable details of a presented error.
FieldErrorsList of FieldErrorWhen a field-level validation occursA 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.

AttributesTypeDescription
FieldStringField associated with the error.
CodeStringIdentifying code of a presented field error.
MessageStringHuman-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

ValueDescription
USDUnited States dollar
EUREuro
CADCanadian dollar
GBPPound
AUDAustralian dollar
BRLBrazilian real
JPYJapanese yen
MXNMexican peso
CHFSwiss franc
SGDSingapore dollar
ILSIsraeli new shekel
NZDNew Zealand dollar
HKDHong Kong dollar
AEDUnited Arab Emirates dirham
SEKSwedish Krona
SARSaudi riyal
DKKDanish krone
NOKNorwegian krone
RUBRussian ruble
MYRMalaysian ringgit
PHPPhilippine peso
THBThai baht
KRWSouth Korean won
INRIndian rupee
CLPChilean peso
PLNPolish złoty
TWDNew Taiwan dollar
TRYTurkish lira
CZKCzech koruna
KWDKuwaiti dinar
QARQatari riyal
ZARSouth African rand
HUFHungarian forint
RONRomanian leu
PENPeruvian sol
IDRIndonesian rupiah
CNYRenminbi
EGPEgyptian pound
ARSArgentine peso
COPColombian peso
ISKIcelandic krona
UAHUkrainian hryvnia
HRKCroatian kuna
BNDBrunei dollar
BHDBahraini dinar
CRCCosta Rican colón
PKRPakistani rupee
BGNBulgarian lev
VNDVietnamese dong
LKRSri Lankan rupee
MOPMacanese pataca
MADMoroccan dirham
GTQGuatemalan quetzal
BMDBermudian dollar
OMROmani rial
RSDSerbian dinar
DOPDominican peso
PABPanamanian balboa
LBPLebanese pound
TTDTrinidad and Tobago Dollar

Session State

ValueFinal State?Description
CREATEDNoSession has been initiated using the Create Session endpoint. A payment may be attempted using the Drop-In.
PROCESSINGNo*Short lived state signifying a payment attempt is being processed.
REDIRECTEDNoState that resembles a user has been redirected away from the Drop-In to complete the payment.
COMPLETEDYesFinal state signifying the user has completed interacting with the Drop-In and an order was created.
CANCELLEDYesFinal state after a merchant has requested a cancellation of a CREATED Session.
FAILEDYesFinal 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

ValueDescription
ProcessingA payment attempt requiring external action (e.g. Bank Transfer).
PaymentAuthorizedPayment has been authorized. If the order is not under review payment capture may proceed.
ProcessedPayment for the order has completed successfully.
ProcessingFailedThe last payment attempt made for the order was not successful.
CancelledThe order was cancelled explicitly by the merchant or the order expired before being captured.
DeclinedThe order was declined as a result of a manual fraud review.