HomeDocumentationAPI Reference
API Reference

Session API guide

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.

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

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

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

ParameterDescription
SessionIdThe unique identifier for the Session object.

Response status

204 No Content

Response body

null

Errors

See the Error Object for more information.

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

ParameterDescription
SessionIdUnique identifier for the Session object.

Request body

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

Examples

The following examples assume you created a session using the full request from the Create a new session examples.

    #Headers
    Content-Type: application/json
    
    #Body
    {
        "SessionId": "91b64778-0d37-479c-ae9f-32f6685ac6ea",
        "State": "CREATED",
        "MerchantReference": "unique_reference_provided_by_merchant",
        "Items": [
            {
                "Name": "Item 1",
                "Amount": 10.0,
                "Quantity": 1
            },
            {
                "Name": "Item 2",
                "Amount": 12.0,
                "Quantity": 2
          }
	    ],
        "Currency": "USD",
        "TotalAmount": 30.0,
        "BillingProfile": {
            "BillingProfileId": "da7e625b-1d6d-4693-9708-e7bdbcb35df3",
            "BillingProfileReference": "MerchantSupplied-reference",
            "Name": "First Last",
            "Email": "[email protected]",
            "NationalIdentifier": "43.236.560/0001-52",
            "Birthdate": "1980-01-02",
            "Company": "Umbrella Corp",
            "Address": {
                "Street": "123 Street",
                "City": "City",
                "Region": "SC",
                "Country": "BR",
                "Postcode": "12345678"
            }
        },
        "ShippingDetails": {
            "Name": "First Last",
            "Email": "[email protected]",
            "Address": {
                "Street": "123 Sreet",
                "City": "City",
                "Region": "AB",
                "Country": "CA",
                "Postcode": "X0X0X0"
            },
            "Phone": "4031231234",
            "ShippingAmount": 0.0,
            "DutyAmount": 0.0
        },
        "TaxAmount": 1.0,
        "AutoCapture": true,
        "CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
        "CancelUrl": "https://www.send-user-here-after-failed-redirect.com",
        "ViaAgent": false,
        "Discounts": [
            {
                "Name": "Discount 1",
                "Amount": 2.0
            },
            {
                "Name": "Discount 2",
                "Amount": 3.0
            }
        ]
    }

Full update

This request updates all the fields in the session. Since we replaced everything, including the items, the object passed in must fully represent the new session.

    # Location
    PUT https://api.withreach.com/v<x>.<yy>/session/91b64778-0d37-479c-ae9f-32f6685ac6ea

    #Headers
    Authorization: Basic YWNjb3VudDpzZWNyZXQ=
    Content-Type: application/json
    
    #Body
    {
        "MerchantReference": "NewReference",
        "Currency": "CAD",
        "Items": [
            {
                "Name": "new Item",
                "Amount": 15.00,
                "Quantity": 1
            }
        ],
        "BillingProfile": {
            "BillingProfileReference": "MerchantSupplied-reference-new",
            "Name": "new name",
            "Email": "[email protected]",
            "Birthdate": "1990-01-02",
            "Company": "New corp",
            "Address": {
                "Street": "123 Sreet",
                "City": "City",
                "Region": "AB",
                "Country": "CA",
                "Postcode": "H0H0H0",
                "Phone": "4031234567"
            }
        },
        "ShippingDetails": {
            "ShippingAmount": 1.00,
            "DutyAmount": 2.00,
            "Name": "First Last",
            "Email": "[email protected]",
            "Phone": "4031231234",
            "Address": {
                "Street": "123 Sreet",
                "City": "City",
                "Region": "AB",
                "Country": "CA",
                "Postcode": "H0H0H0"
            }
        },
        "Discounts": [
            {
                "Name": "Discount 1",
                "Amount": 2.00
            }
        ],
        "TaxAmount": 2.00,
        "AutoCapture": false,
        "CompleteUrl": "https://www.new-success-url.com",
        "CancelUrl": "https://www.new-failure-url.com",
        "ViaAgent": true,
        "AllowContract": true,
        "OpenContract": false
    #Headers
    Content-Type: application/json
    
    #Body
    {
        "SessionId": "91b64778-0d37-479c-ae9f-32f6685ac6ea",
        "State": "CREATED",
        "MerchantReference": "NewReference",
        "Items": [
            {
                "Name": "new Item",
                "Amount": 15.0,
                "Quantity": 1
            }
        ],
        "Currency": "CAD",
        "TotalAmount": 18.0,
        "BillingProfile": {
            "BillingProfileId": "8d89fd08-9b37-4bd9-8b9d-d8250ee6d256",
            "BillingProfileReference": "MerchantSupplied-reference-new",
            "Name": "new name",
            "Email": "[email protected]",
            "Birthdate": "1990-01-02",
            "Company": "New corp",
            "Address": {
                "Street": "123 Sreet",
                "City": "City",
                "Region": "AB",
                "Country": "CA",
                "Postcode": "H0H0H0"
        }
        },
        "ShippingDetails": {
            "Name": "First Last",
            "Email": "[email protected]",
            "Address": {
                "Street": "123 Sreet",
                "City": "City",
                "Region": "AB",
                "Country": "CA",
                "Postcode": "H0H0H0"
            },
            "Phone": "4031231234",
            "ShippingAmount": 1.0,
            "DutyAmount": 2.0
        },
        "Discounts": [
            {
                "Name": "Discount 1",
                "Amount": 2.0
            }
        ],
        "TaxAmount": 2.0,
        "AutoCapture": false,
        "CompleteUrl": "https://www.new-success-url.com",
        "CancelUrl": "https://www.new-failure-url.com",
        "ViaAgent": false,
        "AllowContract": true,
        "OpenContract": false
}

Conditional parameters

Some parameters are conditionally required depending on the country. You can find country-specific validation here. We encourage as much billing information to be passed in as possible to help process the transaction.

The ShippingDetails is required if a physical good is being shipped. We encourage as much shipping information to be passed in as possible to help process the transaction.

The customer billing address may be passed in by passing a single one of the following at the root level of the request:

  • BillingProfile - The full BillingProfile object. Note that this may include a
    BillingProfileReference within this object, a field that can be defined to refer to this reference in the future.
  • BillingProfileReference - a free-text reference you supplied for an existing Billing Profile.
  • BillingProfileId - a Reach-generated ID that refers to a previously generated Billing Profile.

Response status

200 OK

Response body

See the Session object for more information.

Errors

See Error object for more information.

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

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.

AttributesTypeRequired?In Request?Returned WhenDescription
MerchantReferenceStringYesYesAlwaysFree-text unique identifier supplied by the caller.
AutoCaptureBooleanYesYesAlwaysUse an indicator 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.
CancelUrlStringYesYesAlwaysThis 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.
CurrencyEnumYesYesAlwaysThe three-letter ISO-4217 currency code is used to process the payment.
ItemsList of ItemsYesYesAlwaysThe supplied 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 a requestUnique merchant-supplied billing profile reference
BillingProfileIdUUIDYes*Yes*AlwaysReach-generated ID for an existing billing profile
ViaAgentBooleanNoYesAlwaysThis 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.
ShippingDetailsShippingDetailsNoYesWhen supplied in a requestShipping information for a customer.
TaxAmountNumberNoYesWhen supplied in a requestThe tax amount for the order. Will be added to the TotalAmount.
DiscountsList of DiscountNoYesWhen supplied in a 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 the user has completed the Drop-In for the Session.
AllowContractBooleanNoYesWhen supplied in a requestPermit users to create a contract (used for recurring billing, subscriptions, stored payment options, etc.) when submitting their payment.
OpenContractBooleanNoYesWhen supplied in a 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 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.

AttributesTypeRequired?Description
NameStringYesSupplied the name of the item to be paid.
AmountNumberYesSupplied the amount of the item to be paid. The parent object defines currency.
QuantityIntegerYesSupplied 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.

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 a request with a Brazilian CNPJ. See Country Specific FieldsYesBilling profile company
AddressAddressYesYesBilling address.

ShippingDetails object

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 object

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

Discount object

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 object

An order is created once a session is complete. Note that orders will not appear 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 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.

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 the processing bank.
CountryStringCountry of the 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 the 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 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.

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

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
CREATEDNoThe session was initiated using the Create Session endpoint. A shopper may attempt payment using the Drop-In.
PROCESSINGNo*A short-lived state signifying a payment attempt is being processed.
REDIRECTEDNoThis state indicates Drop-In redirected the shopper to the payment provider to complete the payment.
COMPLETEDYesThis final state signifies that the user has completed interacting with the Drop-In and Drop-In has created an order.
CANCELLEDYesThis final state indicates a merchant has requested the cancellation of a CREATED Session.
FAILEDYesThis 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
ProcessingA payment attempt requiring external action (e.g., Bank Transfer).
PaymentAuthorizedThe payment provider authorized the payment. If the order is not under review, payment capture may proceed.
ProcessedPayment for the order has completed successfully.
ProcessingFailedThe last payment attempt for the order was not successful.
CancelledThe merchant canceled the order explicitly, or the order expired before being captured.
DeclinedReach declined the order as a result of a manual fraud review.