--- updatedAt: 2025-08-26T19:55:10.000Z agentTools: projectIndex: https://docs.withreach.com/llms.txt --- # Create a new session # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Reach's Drop-In API", "description": "API definition for Reach's Drop-In API's", "version": "1.0.0" }, "servers": [ { "url": "https://api.sandbox.withreach.com" }, { "url": "https://api.withreach.com" } ], "tags": [ { "name": "Session", "description": "Manage a Session within Reach." } ], "paths": { "/v1/session": { "post": { "tags": [ "Session" ], "summary": "Create a new Session", "operationId": "createSession", "security": [ { "basicAuth": [] } ], "requestBody": { "description": "Session object that needs to be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" }, "examples": { "BasicExample": { "summary": "A basic session creation with valid fields", "value": { "MerchantReference": "b14e4557-accb-a829-b829-c21234175467", "Currency": "CAD", "Items": [ { "Name": "Item 1", "Amount": 23, "Quantity": 1 }, { "Name": "Item 2", "Amount": 10.5, "Quantity": 1 }, { "Name": "Item 3", "Amount": 5, "Quantity": 1 } ], "BillingProfile": { "Name": "First Last", "Email": "email@example.org", "Phone": "4031231234", "Birthdate": "1999-12-31", "Address": { "Street": "123 Street", "City": "City", "Region": "AB", "Country": "CA", "Postcode": "X0X0X0" } }, "ShippingDetails": { "ShippingAmount": 20.51, "DutyAmount": 1.11, "Name": "First Last", "Email": "email@example.org", "Phone": "4031231234", "Address": { "Street": "123 Street", "City": "City", "Region": "AB", "Country": "AR", "Postcode": "X0X0X0" } }, "TaxAmount": 1.23, "AutoCapture": true, "CompleteUrl": "https://example.org/return/{SessionId}", "CancelUrl": "https://example.org/return/{SessionId}", "Discounts": [ { "Name": "Discount descriptor", "Amount": 4.56 } ] } }, "Minimal": { "summary": "A request with only the required fields.", "value": { "MerchantReference": "unique_reference_provided_by_merchant", "Currency": "USD", "Items": [ { "Name": "Item 1", "Amount": 10, "Quantity": 1 } ], "BillingProfile": { "Name": "First Last", "Email": "email@example.org", "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" } }, "Full": { "summary": "A request with all optional fields included", "value": { "MerchantReference": "unique_reference_provided_by_merchant", "Currency": "USD", "Items": [ { "Name": "Item 1", "Amount": 10, "Quantity": 1 }, { "Name": "Item 2", "Amount": 12, "Quantity": 2 } ], "BillingProfile": { "BillingProfileReference": "MerchantSupplied-reference", "Name": "First Last", "Email": "email@example.org", "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, "DutyAmount": 0, "Name": "First Last", "Email": "email@example.org", "Phone": "4031231234", "Address": { "Street": "123 Sreet", "City": "City", "Region": "AB", "Country": "CA", "Postcode": "X0X0X0" } }, "Discounts": [ { "Name": "Discount 1", "Amount": 2 }, { "Name": "Discount 2", "Amount": 3 } ], "TaxAmount": 1, "AutoCapture": true, "CompleteUrl": "https://www.send-user-here-after-success-redirect.com", "CancelUrl": "https://www.send-user-here-after-failed-redirect.com", "ViaAgent": false, "Meta": { "TxnId": 1234567, "InternalRefId": "uuid-1234-abcd" }, "AllowContract": true, "OpenContract": false, "TaxQuoteId": "unique-tax-uuid" } }, "BillingProfileReference": { "summary": "A request using a BillingProfileReference", "value": { "MerchantReference": "unique_reference_provided_by_merchant", "Currency": "USD", "Items": [ { "Name": "Item 1", "Amount": 10, "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" } }, "BillingProfileId": { "summary": "A request using a BillingProfileId", "value": { "MerchantReference": "unique_reference_provided_by_merchant", "Currency": "USD", "Items": [ { "Name": "Item 1", "Amount": 10, "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" } } } } }, "required": true }, "responses": { "200": { "description": "Operation Successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" }, "example": { "SessionId": "f04c2d83-11fa-405b-b6c3-c74559fd8e61", "State": "CREATED", "MerchantReference": "b14e4557-accb-a829-b829-c21234175467", "Currency": "CAD", "TotalAmount": 43.18, "Items": [ { "Name": "Item 1", "Amount": 23, "Quantity": 1 }, { "Name": "Item 2", "Amount": 10.5, "Quantity": 1 }, { "Name": "Item 3", "Amount": 5, "Quantity": 1 } ], "BillingProfile": { "BillingProfileId": "68bf47c6-787d-4ca2-a904-27870f7e75ef", "Name": "First Last", "Email": "email@example.org", "Phone": "4031231234", "Birthdate": "1999-12-31", "Address": { "Street": "123 Street", "City": "City", "Region": "AB", "Country": "CA", "Postcode": "X0X0X0" } }, "ShippingDetails": { "ShippingAmount": 2.34, "DutyAmount": 1.11, "Name": "First Last", "Email": "email@example.org", "Phone": "4031231234", "Address": { "Street": "123 Street", "City": "City", "Region": "AB", "Country": "AR", "Postcode": "X0X0X0" } }, "TaxAmount": 1.23, "AutoCapture": true, "CompleteUrl": "https://example.org/return/f04c2d83-11fa-405b-b6c3-c74559fd8e61", "CancelUrl": "https://example.org/return/f04c2d83-11fa-405b-b6c3-c74559fd8e61", "ViaAgent": false, "Discounts": [ { "Name": "Discount descriptor", "Amount": 4.56 } ], "AllowContract": true, "OpenContract": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid request error": { "value": { "Code": "INVALID_REQUEST", "Message": "Invalid request syntax", "FieldErrors": [ { "Field": "Currency", "Code": "FIELD_MISSING", "Message": "Currency is a required field but was not included in the request" } ] } }, "Invalid Currency Error": { "value": { "Code": "INVALID_CURRENCY", "Message": "Provided currency is not supported" } } } } } }, "401": { "description": "Authentication Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Authentication required error": { "value": { "Code": "AUTHENTICATION_REQUIRED", "Message": "Username/password must be supplied to access this resource" } }, "Invalid username/password error": { "value": { "Code": "AUTHENTICATION_REQUIRED", "Message": "Supplied username/password are invalid" } } } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "Code": "NOT_AUTHORIZED", "Message": "User is not permitted to access this resource" } } } }, "409": { "description": "Duplicate merchant reference ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "Code": "DUPLICATE_MERCHANT_REFERENCE_ID", "Message": "Session with merchant reference already exists" } } } }, "415": { "description": "Unsupported Media Type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "Code": "UNSUPPORTED_MEDIA_TYPE", "Message": "Expected content-type: application/json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "Code": "INTERNAL_SERVER_ERROR", "Message": "The server could not process the request due to an unexpected error" } } } } } } } }, "components": { "schemas": { "Session": { "type": "object", "properties": { "SessionId": { "description": "Returned UUID representing the Session", "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36, "readOnly": true }, "State": { "description": "Returned state of the Session.", "type": "string", "enum": [ "CREATED", "REDIRECTED", "COMPLETED", "CANCELLED", "FAILED" ], "readOnly": true }, "MerchantReference": { "description": "Unique identifier provided by merchant.", "type": "string", "minLength": 1 }, "Currency": { "description": "Three-character ISO-4217 currency code used to process the payment.", "type": "string", "minLength": 3, "maxLength": 3 }, "TotalAmount": { "description": "Sum of all item amounts, TaxAmount, ShippingDetails.ShippingAmount and ShippingDetails.DutyAmount, minus the total of all Discounts", "type": "number", "format": "float", "readOnly": true }, "Items": { "description": "List of items to be paid. At least one Item must be supplied.", "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "AutoCapture": { "description": "Indicator used to determine if an Order is auto captured after authorization.", "type": "boolean" }, "CompleteUrl": { "description": "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.", "type": "string", "minLength": 1, "example": "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": { "description": "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.", "type": "string", "minLength": 1, "example": "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}" }, "ViaAgent": { "description": "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.", "type": "boolean" }, "BillingProfileId": { "description": "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.", "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36, "writeOnly": true }, "BillingProfileReference": { "description": "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.", "type": "string", "minLength": 1, "writeOnly": true }, "BillingProfile": { "description": "Full consumer billing information. Supplying this creates a new BillingProfile that can be referenced in future requests with either the supplied BillingProfileReference or the generated BillingProfileId. Exactly one of BillingProfile, BillingProfileId or BillingprofileReference are required.", "allOf": [ { "$ref": "#/components/schemas/BillingProfile" } ] }, "ShippingDetails": { "description": "Consumer shipping information. Required if the session is for physical goods.", "allOf": [ { "$ref": "#/components/schemas/ShippingDetails" } ] }, "TaxAmount": { "description": "Taxes for the entire order. Currency is defined by parent object.", "type": "number" }, "Order": { "description": "Order information, returned when a session is completed.", "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Order" } ] }, "Discounts": { "type": "array", "items": { "$ref": "#/components/schemas/Discount" } }, "RateOfferId": { "description": "The 36 character GUID for a guaranteed foreign exchange rate. If omitted, the rate will be determined at the time of settlement.", "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36 }, "Meta": { "$ref": "#/components/schemas/Meta" }, "PaymentDate": { "description": "Date of /payment call against the session. Only present for completed sessions.", "type": "string", "readOnly": true }, "PaymentMethod": { "description": "Method used as part of a /payment call against the session. Only present for completed sessions.", "type": "string", "readOnly": true }, "AllowContract": { "description": "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.", "type": "boolean" }, "OpenContract": { "description": "Flag to tell that the payment is to be used to start a subscription and if successful will automatically create a contract.", "type": "boolean" }, "TaxQuoteId": { "description": "Unique Tax Quote Id provided by merchant, Id recieved from calling the Reach Quote API.", "type": "string", "minLength": 1 } }, "required": [ "MerchantReference", "Currency", "Items", "AutoCapture", "CompleteUrl", "CancelUrl" ] }, "Order": { "description": "A Reach order, representing a payment attempt. See https://docs.withreach.com/docs/states-and-events for information on the order lifecycle. If created by a session, the presence indicates the session is completed and the payment is being processed.", "type": "object", "properties": { "OrderId": { "description": "UUID identifying the individual Order.", "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36, "readOnly": true }, "SessionId": { "description": "UUID representing the Session", "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36, "readOnly": true }, "State": { "description": "Order state. See: https://docs.withreach.com/docs/states-and-events", "type": "string", "enum": [ "AUTHENTICATING", "PENDING", "PROCESSING", "PAYMENTAUTHORIZED", "PROCESSED", "PROCESSINGFAILED", "CANCELLED", "DECLINED" ], "readOnly": true }, "MerchantReference": { "description": "Unique identifier provided by merchant.", "type": "string", "minLength": 1 }, "BillingProfile": { "description": "Full consumer billing information. Supplying this creates a new BillingProfile that can be referenced in future requests with either the supplied BillingProfileReference or the generated BillingProfileId. Exactly one of BillingProfile, BillingProfileId or BillingprofileReference are required.", "allOf": [ { "$ref": "#/components/schemas/BillingProfile" } ] }, "BillingProfileId": { "description": "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.", "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36, "writeOnly": true }, "BillingProfileReference": { "description": "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.", "type": "string", "minLength": 1, "writeOnly": true }, "Currency": { "description": "Three-character ISO-4217 currency code used to process the payment.", "type": "string", "minLength": 3, "maxLength": 3 }, "Items": { "description": "List of items to be paid. At least one Item must be supplied in requests. The sum total of the item amounts will be added to the TotalAmount", "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "Payment": { "description": "Payment information, such as card or offline data. Required in requests if ContractId is not present.", "allOf": [ { "$ref": "#/components/schemas/Payment" } ] }, "ContractId": { "description": "Reach-generated ID of an existing contract. Can be supplied in lieu of a Payment object. Will be returned in the response if OpenContract is set to true.", "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36 }, "DeviceFingerprint": { "description": "Device fingerprint - see https://docs.withreach.com/reference/fingerprint-1", "type": "string", "minLength": 1, "writeOnly": true }, "Discounts": { "description": "List of discounts. The sum of the discounts amounts will be subtracted from the TotalAmount", "type": "array", "items": { "$ref": "#/components/schemas/Discount" } }, "ShippingDetails": { "$ref": "#/components/schemas/ShippingDetails" }, "TaxAmount": { "description": "Tax to be applied to the order. In the consumer currency, max precision of 2 digits. TaxAmount will be added to the TotalAmount.", "type": "number" }, "ViaAgent": { "description": "Indicates that this order is being made by an agent, and not the end consumer. If false or not present, the order is assumed to be placed by the end consumer.", "type": "boolean", "writeOnly": true }, "AcceptLiability": { "description": "If true, the merchant accepts financial liability for this order.", "type": "boolean", "writeOnly": true }, "AutoCapture": { "description": "If true or the payment method used by the consumer does not support pre-authorization, the payment will be completed. If false or not present, and the payment method supports pre-authorization, the order will be left in the PaymentAuthorized state and the merchant must capture the order using a capture request.", "type": "boolean", "writeOnly": true }, "OpenContract": { "description": "If true, a contract (used for recurring billing, subscriptions, stored payment options, etc.) will be opened if possible. If false or not present, the order will not open a contract.", "type": "boolean", "writeOnly": true }, "TaxQuoteId": { "description": "Unique Tax Quote Id provided by merchant, Id recieved from calling the Reach Quote API.", "type": "string", "minLength": 1 }, "Meta": { "$ref": "#/components/schemas/Meta" }, "UnderReview": { "description": "This will be returned as true if a fraud review is in progress for the order. Payment cannot be processed until the review has been completed.", "type": "boolean", "readOnly": true }, "Chargeback": { "description": "This will be returned as true if a chargeback has been issued against the order. An outstanding chargeback disables the ability to submit a refund against the order.", "type": "boolean", "readOnly": true }, "Reason": { "description": "Gives a reason for an order to be in a given state.", "type": "string", "readOnly": true }, "Expiry": { "description": "If the order was created with Capture false, and the payment is authorized, the RFC 3339 time at which this order expires. If further authentication is required, this is the time by which that authentication must be completed.", "type": "string", "readOnly": true }, "Action": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Action" } ] }, "Times": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Times" } ] }, "AdminUrl": { "description": "A link to this order in the Reach admin app. You must have valid credentials to view", "type": "string", "readOnly": true } }, "required": [ "OrderId", "State", "MerchantReference" ] }, "Item": { "description": "A line item, representing one or more digital or physical goods that a user is paying for.", "type": "object", "properties": { "Name": { "description": "Free-text field to identify a line item.", "type": "string", "minLength": 1 }, "Amount": { "description": "Amount of item to be paid. Currency is defined by parent object.", "type": "number", "format": "float" }, "Quantity": { "description": "Quantity of the item to be paid.", "type": "integer" } }, "required": [ "Name", "Amount", "Quantity" ] }, "Discount": { "description": "A merchant-supplied discount on the entire order. The amount will be subtracted from TotalAmount", "type": "object", "properties": { "Name": { "description": "A free-text name to describe the discount", "type": "string", "minLength": 1 }, "Amount": { "description": "Flat amount of the discount to be applied.", "type": "number", "format": "float" } }, "required": [ "Name", "Amount" ] }, "BillingProfile": { "description": "Billing details associated with the payment. Some fields may be required or optional depending on the Country in BillingProfile.Address. See: https://docs.withreach.com/reference/country-specific-fields-1", "type": "object", "properties": { "BillingProfileId": { "description": "A UUID for a given BillingProfile object present in Reach. This can be used later to reference an existing consumer", "type": "string", "readOnly": true }, "BillingProfileReference": { "description": "A unique merchant-supplied consumer identifier. If supplied, this can be used later to reference an existing consumer.", "type": "string", "minLength": 1 }, "Name": { "description": "Customer’s given name.", "type": "string", "minLength": 1 }, "Company": { "description": "Customer's company name.", "type": "string", "minLength": 1 }, "Email": { "description": "Customer’s email address", "type": "string", "minLength": 1 }, "Address": { "$ref": "#/components/schemas/Address" }, "Phone": { "description": "Customer's phone number.", "type": "string", "minLength": 1 }, "Birthdate": { "description": "Customer's birthdate (format yyyy-MM-dd). Required depending on the Country.", "type": "string", "minLength": 1 }, "NationalIdentifier": { "description": "National ID, such as SSN or CPF. Required depending on the Country.", "type": "string", "minLength": 1 } }, "required": [ "Name", "Email", "Address", "City", "Country" ] }, "ShippingDetails": { "description": "Customer's shipping details. This is required if physical goods are shipped along with the order.", "type": "object", "properties": { "ShippingAmount": { "description": "Total amount excluding taxes and duties. Currency is defined by parent object.", "type": "number" }, "DutyAmount": { "description": "Duty for the entire order. Currency is defined by parent object.", "type": "number" }, "Name": { "description": "Customer’s given name.", "type": "string", "minLength": 1 }, "Company": { "description": "Company's name.", "type": "string", "minLength": 1 }, "Email": { "description": "Customer’s email address", "type": "string", "minLength": 1 }, "Address": { "$ref": "#/components/schemas/Address" } }, "required": [ "Price", "Tax", "Duty", "Name", "Address", "City", "Country" ] }, "Address": { "description": "A shipping or billing address", "type": "object", "properties": { "Street": { "description": "Customer's street address.", "type": "string", "minLength": 1 }, "City": { "description": "Customer's city.", "type": "string", "minLength": 1 }, "Region": { "description": "Customer's state or province. The region code is the region-only portion of an ISO-3166-2 region (ex. MX-GUA would be sent as \"GUA\")", "type": "string", "minLength": 2, "maxLength": 3 }, "Country": { "description": "Customer's country (upper-case ISO 3166 alpha-2 country code).", "type": "string", "minLength": 2, "maxLength": 2 }, "Postcode": { "description": "Customer's zip/postal code.", "type": "string", "minLength": 1 } }, "required": [ "Street", "City", "Country" ] }, "Payment": { "description": "Object representing the payment information for an order", "type": "object", "properties": { "Type": { "description": "Payment classification", "type": "string", "enum": [ "CARD", "ONLINE", "OFFLINE" ] }, "Method": { "description": "Specific payment method as returned in Name of getPaymentMethods. See: https://docs.withreach.com/reference/getpaymentmethods", "type": "string", "minLength": 1, "example": "VISA, IDEAL, BANK" }, "ReturnUrl": { "description": "Merchant URL to redirect a user to upon completion at a third party payment processor or a 3DS challenge. This may contain \"{SessionId}\" anywhere in the string to have the SessionId embedded in the url.", "type": "string", "example": "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}", "writeOnly": true }, "Online": { "description": "Represents online payment methods, such as Paypal or Klarna. Present if Payment.Type is ONLINE, otherwise absent.", "allOf": [ { "$ref": "#/components/schemas/Online" } ] }, "Card": { "description": "Represents card payment methods, such as Visa or Mastercard. Present if Payment.Type is CARD, otherwise absent.", "allOf": [ { "$ref": "#/components/schemas/Card" } ] }, "Offline": { "description": "Represents offline payment methods, such as Bank Transfers. Present if Payment.Type is OFFLINE, otherwise absent.", "allOf": [ { "$ref": "#/components/schemas/Offline" } ] } } }, "Online": { "description": "Contains payment details for Online payment types.", "type": "object", "properties": { "Locale": { "description": "Locale for redirects. May need to be customized to a specific payment type.", "type": "string", "minLength": 1, "example": "en-us" }, "Ideal": { "$ref": "#/components/schemas/Ideal" }, "Paypal": { "$ref": "#/components/schemas/Paypal" } } }, "Ideal": { "description": "Payment details specific to iDeal.", "type": "object", "properties": { "IssuerId": { "description": "iDeal-specific Issuer ID, to be passed to the processor", "type": "string", "minLength": 1, "writeOnly": true } } }, "Paypal": { "description": "Payment details specific to PayPal.", "type": "object", "properties": { "Email": { "description": "Email associated with the customer's PayPal account, as they entered in a redirect", "type": "string", "readOnly": true } } }, "Card": { "description": "Payment details for Card type. Must be supplied if Payment.Type is CARD", "type": "object", "properties": { "StashId": { "description": "Details of a card payment returned from a stash call. See: https://docs.withreach.com/docs/stash", "type": "string", "minLength": 1, "writeOnly": true }, "Bin": { "description": "First 6 digits of a card number. Used for display purposes", "type": "string", "readOnly": true }, "LastFour": { "description": "Last 4 digits of a card number. Used for display purposes.", "type": "string", "readOnly": true }, "Expiry": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Expiry" } ] } } }, "Expiry": { "description": "Card expiry information", "type": "object", "properties": { "Month": { "description": "Month the card expires in. Returned as 2-character numeric.", "type": "string" }, "Year": { "description": "Year the card expires. Returned as a 4-character numeric.", "type": "string" } } }, "Offline": { "description": "Offline payment information.", "type": "object" }, "Action": { "description": "If additional action must be taken to proceed with a request, this object contains information about the required action.", "type": "object", "properties": { "Redirect": { "description": "URL to redirect a consumer on completion", "type": "string" }, "Challenge": { "description": "The URL to use for iframe-embedded authentication (ex. 3-DSecure v2, WeChat QR code, etc.)", "type": "string" }, "Display": { "$ref": "#/components/schemas/Display" } } }, "Display": { "description": "A freeform JSON object which, in the context of the specified request, gives the necessary information for a consumer to proceed. See https://docs.withreach.com/docs/display-parameters.", "type": "object", "properties": { "AccountHolder": { "type": "string" }, "AccountNumber": { "type": "string" }, "BankName": { "type": "string" }, "City": { "type": "string" }, "Iban": { "type": "string" }, "PaymentReference": { "type": "string" }, "SwiftCode": { "type": "string" }, "ExtraBankData": { "type": "string" } } }, "Times": { "description": "Gives times of various order state transitions", "type": "object", "properties": { "Created": { "description": "The RFC 3339 timestamp at which the order was created.", "type": "string" }, "Authorized": { "description": "The RFC 3339 timestamp at which the order’s payment was authorized. This will be null if the payment has not yet been authorized or the payment method used for the order does not support pre-authorization (eg. Boleto).", "type": "string" }, "Processed": { "description": "The RFC 3339 timestamp at which the order's payment was processed. This will be null if the order's payment has not been processed yet or has failed to be processed.", "type": "string" } } }, "Error": { "type": "object", "properties": { "Code": { "description": "Identifying code of a presented error.", "type": "string" }, "Message": { "description": "Details of a presented error.", "type": "string" }, "FieldErrors": { "description": "A list of field errors.", "type": "array", "items": { "$ref": "#/components/schemas/FieldErrors" } } }, "required": [ "Code", "Message" ] }, "FieldErrors": { "type": "object", "properties": { "Field": { "description": "Field associated with the error.", "type": "string" }, "Code": { "description": "Identifying code of a presented field error.", "type": "string" }, "Message": { "description": "Details of a presented field error.", "type": "string" } }, "required": [ "Field", "Code", "Message" ] }, "Meta": { "description": "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.", "type": "object", "example": "{\"Custom field\": \"Any value\"}" } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```