v1

latestOpenAPI 3.0.02026-07-262832203.2 KB

Session

Create a new Session

post/v1/session

Request body

SessionIdstring uuid

Returned UUID representing the Session

State'CREATED' | 'REDIRECTED' | 'COMPLETED' | 'CANCELLED' | 'FAILED'

Returned state of the Session.

MerchantReferencestring required

Unique identifier provided by merchant.

Currencystring required

Three-character ISO-4217 currency code used to process the payment.

TotalAmountnumber float

Sum of all item amounts, TaxAmount, ShippingDetails.ShippingAmount and ShippingDetails.DutyAmount, minus the total of all Discounts

AutoCaptureboolean required

Indicator used to determine if an Order is auto captured after authorization.

CompleteUrlstring required

Merchant URL to redirect a user to upon completion at a third party payment processor. This may contain "{SessionId}" anywhere in the string to have the SessionId embedded in the url.

CancelUrlstring required

Merchant URL to redirect a user to after cancelling on a third party payment processor. This may contain "{SessionId}" anywhere in the string to have the SessionId embedded in the url.

ViaAgentboolean

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.

BillingProfileIdstring uuid

Corresponds to the BillingProfileId returned in a BillingProfile. Can be passed in to reference an existing billing profile instead of creating a new one. Exactly one of BillingProfile, BillingProfileId or BillingprofileReference are required.

BillingProfileReferencestring

Merchant supplied reference that uniquely maps to a BillingProfile. Can be passed in to reference an existing BillingProfile. Exactly one of BillingProfile, BillingProfileId or BillingprofileReference are required.

TaxAmountnumber

Taxes for the entire order. Currency is defined by parent object.

RateOfferIdstring uuid

The 36 character GUID for a guaranteed foreign exchange rate. If omitted, the rate will be determined at the time of settlement.

MetaMeta

Any optional metadata to be included. Can be a simple reference ID or some complex object containing multiple values, as long as it is valid JSON.

PaymentDatestring

Date of /payment call against the session. Only present for completed sessions.

PaymentMethodstring

Method used as part of a /payment call against the session. Only present for completed sessions.

AllowContractboolean

Overrides the merchant AllowContract setting to permit users creation of a contract (used for recurring billing, subscriptions, stored payment options, etc.) when submitting their payment.

OpenContractboolean

Flag to tell that the payment is to be used to start a subscription and if successful will automatically create a contract.

TaxQuoteIdstring

Unique Tax Quote Id provided by merchant, Id recieved from calling the Reach Quote API.

Example request

{
  "CompleteUrl": "https://example.org/return, https://example.org/return?param=12345&hello=world, https://example.org/return/{SessionId}, https://example.org/{SessionId}/return, https://example.org/return?SessionId={SessionId}",
  "CancelUrl": "https://example.org/return, https://example.org/return?param=12345&hello=world, https://example.org/return/{SessionId}, https://example.org/{SessionId}/return, https://example.org/return?SessionId={SessionId}",
  "BillingProfile": {
    "Address": {
      "Street": "123 Main St",
      "City": "Los Angeles",
      "Region": "CA",
      "Country": "US",
      "Postcode": "90001"
    }
  },
  "ShippingDetails": {
    "Address": {
      "Street": "123 Main St",
      "City": "Los Angeles",
      "Region": "CA",
      "Country": "US",
      "Postcode": "90001"
    }
  },
  "Order": {
    "BillingProfile": {
      "Address": {
        "Street": "123 Main St",
        "City": "Los Angeles",
        "Region": "CA",
        "Country": "US",
        "Postcode": "90001"
      }
    },
    "Payment": {
      "Method": "VISA, IDEAL, BANK",
      "ReturnUrl": "https://example.org/return, https://example.org/return?param=12345&hello=world, https://example.org/return/{SessionId}, https://example.org/{SessionId}/return, https://example.org/return?SessionId={SessionId}",
      "Online": {
        "Locale": "en-us"
      }
    },
    "ShippingDetails": {
      "Address": {
        "Street": "123 Main St",
        "City": "Los Angeles",
        "Region": "CA",
        "Country": "US",
        "Postcode": "90001"
      }
    }
  }
}

Response

Operation Successful