{ "openapi" : "3.0.0", "info" : { "version" : "v1", "title" : "Encoded Gateway API", "license" : { "name" : "Proprietary" }, "description" : "The Encoded Gateway API can be used to create and manage Orders, Customers, Transactions and Tokens." }, "servers" : [ { "url" : "https://{environment}.encoded.services/api/v1", "variables" : { "environment" : { "default" : "sit", "description" : "The API Environment.", "enum" : [ "prod", "sit" ] } } } ], "security" : [ { "accessCode" : [ "read", "write", "session_limited_read" ] } ], "tags" : [ { "name" : "Customers", "description" : "Create, Read, Update and Delete customers." }, { "name" : "Orders", "description" : "Create, Read, Update and Delete orders." }, { "name" : "Transactions", "description" : "Create and Read transactions." }, { "name" : "Tokens", "description" : "Read tokens." }, { "name" : "Challenges", "description" : "Submit challenge responses" }, { "name" : "Sessions", "description" : "Create and Update payment sessions" } ], "paths" : { "/customers" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "listCustomers", "tags" : [ "Customers" ], "summary" : "Returns a list of Customers", "description" : "10 per page by default. Can be filtered by custom attributes using the filter parameter.", "parameters" : [ { "$ref" : "#/components/parameters/refParam" }, { "$ref" : "#/components/parameters/filterParam" }, { "$ref" : "#/components/parameters/pageParam" }, { "$ref" : "#/components/parameters/resultsParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200CustomerList" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } }, "post" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "createCustomers", "tags" : [ "Customers" ], "summary" : "Create new customers.", "description" : "Inserts an array of provided Customers. If there is a problem with one of the customer objects given, none will be created and you will have to retry using the validation information given in the response.", "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Customer" } } } } }, "responses" : { "201" : { "description" : "Created" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/customers/{customer_id}" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "getCustomer", "tags" : [ "Customers" ], "summary" : "Find a customer by ID.", "parameters" : [ { "$ref" : "#/components/parameters/customerIdParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200Customer" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } }, "put" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "updateCustomer", "tags" : [ "Customers" ], "summary" : "Update a customer.", "parameters" : [ { "$ref" : "#/components/parameters/customerIdParam" } ], "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Customer" } } } }, "responses" : { "200" : { "$ref" : "#/components/responses/200Customer" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } }, "delete" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "deleteCustomer", "tags" : [ "Customers" ], "summary" : "Delete a customer.", "parameters" : [ { "$ref" : "#/components/parameters/customerIdParam" } ], "responses" : { "204" : { "$ref" : "#/components/responses/204NoContent" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/expresshpp" : { "post" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "createExpressHostedPaymentPage", "tags" : [ "ExpressHPP" ], "summary" : "Creates a hosted payment page from a URL encoded form with all relevant data", "requestBody" : { "required" : true, "content" : { "application/x-www-form-urlencoded" : { "schema" : { "type" : "object", "description" : "URL encoded form data used to create an order and generate a Hosted Payment Page link in a single request.", "required" : [ "description", "currency", "amount" ], "properties" : { "ref" : { "type" : "string", "description" : "A reference supplied by the API user to identify the order. The reference may be used to search for this order and is not required to be unique by default." }, "description" : { "type" : "string", "description" : "A human readable description of the order." }, "currency" : { "type" : "string", "format" : "ISO4217", "description" : "The currency of the order, in ISO 4217 format." }, "amount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The total amount of the order, including taxes. Must be greater than or equal to zero and have no more than 2 decimal places.", "minimum" : 0 }, "action" : { "type" : "string", "enum" : [ "authorise", "pay", "refund", "verify" ], "description" : "The case insensitive transaction action to perform from the Hosted Payment Page." }, "customerTitle" : { "type" : "string", "description" : "The billing customer's title." }, "customerForename" : { "type" : "string", "description" : "The customer's forename." }, "customerSurname" : { "type" : "string", "description" : "The customer's surname." }, "customerEmail" : { "type" : "string", "format" : "email", "description" : "The customer's contact email address." }, "customerPhone" : { "type" : "string", "description" : "The customer's mobile telephone number." }, "customerAddressLine1" : { "type" : "string", "description" : "The first line of the customer's address." }, "customerAddressLine2" : { "type" : "string", "description" : "The second line of the customer's address." }, "customerAddressLine3" : { "type" : "string", "description" : "The third line of the customer's address." }, "customerAddressCounty" : { "type" : "string", "description" : "The customer's address county." }, "customerAddressPostcode" : { "type" : "string", "description" : "The customer's address post code." }, "customerAddressCountry" : { "type" : "string", "format" : "ISO 3166 Alpha-3", "description" : "The customer's address country in ISO 3166 Alpha-3 format." }, "returnUrl" : { "type" : "string", "format" : "URL", "description" : "The return URL a Hosted Payment Page will be directed to after a payment result is returned." }, "merchantAccount" : { "type" : "integer", "description" : "The merchant account ID requested for processing Hosted Payment Page transactions." }, "musqetBitcoinEnabled" : { "type" : "boolean", "description" : "Whether Musqet Bitcoin payments are enabled on the Hosted Payment Page." }, "googlePayEnabled" : { "type" : "boolean", "description" : "Whether Google Pay is enabled on the Hosted Payment Page." }, "applePayEnabled" : { "type" : "boolean", "description" : "Whether Apple Pay is enabled on the Hosted Payment Page." }, "clickToPayEnabled" : { "type" : "boolean", "description" : "Whether Click to Pay is enabled on the Hosted Payment Page." }, "expiryDate" : { "type" : "string", "format" : "date-time", "description" : "The date and time after which the Hosted Payment Page will no longer accept payment attempts." }, "expiryDuration" : { "type" : "string", "description" : "Java duration value accepted by the API." }, "typeAllow" : { "type" : "array", "description" : "Card funding types that are allowed for card payments.", "items" : { "type" : "string" } }, "typeDeny" : { "type" : "array", "description" : "Card funding types that are denied for card payments.", "items" : { "type" : "string" } }, "schemeAllow" : { "type" : "array", "description" : "Card schemes that are allowed for card payments.", "items" : { "type" : "string" } }, "schemeDeny" : { "type" : "array", "description" : "Card schemes that are denied for card payments.", "items" : { "type" : "string" } } } } } } }, "responses" : { "200" : { "description" : "OK", "content" : { "text/plain" : { "schema" : { "type" : "string", "format" : "uri", "description" : "The return URL a Hosted Payment Page will be directed to after a payment result is returned." } } } }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "403" : { "$ref" : "#/components/responses/403JWTMismatchExpressHpp" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/customers/{customer_id}/tokens" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "listCustomerTokens", "tags" : [ "Customers", "Tokens" ], "summary" : "Retrieve a list of customer's tokens.", "description" : "Retrieve a list of the identified customer's tokens. Default 10 per page.", "parameters" : [ { "$ref" : "#/components/parameters/customerIdParam" }, { "$ref" : "#/components/parameters/refParam" }, { "$ref" : "#/components/parameters/filterParam" }, { "$ref" : "#/components/parameters/pageParam" }, { "$ref" : "#/components/parameters/resultsParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200TokenList" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/customers/{customer_id}/tokens/{token_id}" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "getCustomerToken", "tags" : [ "Customers", "Tokens" ], "summary" : "Retrieve a specific token belonging to a customer.", "parameters" : [ { "$ref" : "#/components/parameters/customerIdParam" }, { "$ref" : "#/components/parameters/tokenIdParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200Token" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } }, "patch" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "updateCustomerToken", "tags" : [ "Customers", "Tokens" ], "summary" : "Update a token's attributes or expiry date.", "parameters" : [ { "$ref" : "#/components/parameters/customerIdParam" }, { "$ref" : "#/components/parameters/tokenIdParam" } ], "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TokenInput" } } } }, "responses" : { "200" : { "$ref" : "#/components/responses/200Token" }, "400" : { "$ref" : "#/components/responses/400TokenMismatch" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } }, "delete" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "deleteCustomerToken", "tags" : [ "Customers", "Tokens" ], "summary" : "Delete a token", "parameters" : [ { "$ref" : "#/components/parameters/customerIdParam" }, { "$ref" : "#/components/parameters/tokenIdParam" } ], "responses" : { "204" : { "$ref" : "#/components/responses/204NoContent" }, "400" : { "$ref" : "#/components/responses/400TokenMismatch" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/hpp/config/{access_level}" : { "post" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "setHostedPaymentPageConfig", "tags" : [ "HPP Config" ], "summary" : "Set the user access level-wide configuration of Hosted Payment Pages", "parameters" : [ { "$ref" : "#/components/parameters/accessLevelParam" } ], "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HostedPaymentPageConfigInput" } } } }, "responses" : { "200" : { "description" : "Successfully updated Hosted Payment Page config" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/tokens" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "listTokens", "tags" : [ "Tokens" ], "summary" : "Retrieve a list of tokens.", "description" : "Retrieve a list of tokens. Default 10 per page. Can be filtered using the filter parameter.", "parameters" : [ { "$ref" : "#/components/parameters/refParam" }, { "$ref" : "#/components/parameters/filterParam" }, { "$ref" : "#/components/parameters/pageParam" }, { "$ref" : "#/components/parameters/resultsParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200TokenList" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/tokens/{token_id}" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "getToken", "tags" : [ "Tokens" ], "summary" : "Retrieve a specific token.", "parameters" : [ { "$ref" : "#/components/parameters/tokenIdParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200Token" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } }, "patch" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "updateToken", "tags" : [ "Tokens" ], "summary" : "Update a tokens attributes or expiry date.", "parameters" : [ { "$ref" : "#/components/parameters/tokenIdParam" } ], "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TokenInput" } } } }, "responses" : { "200" : { "$ref" : "#/components/responses/200Token" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } }, "delete" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "deleteToken", "tags" : [ "Tokens" ], "summary" : "Delete a token", "parameters" : [ { "$ref" : "#/components/parameters/tokenIdParam" } ], "responses" : { "204" : { "$ref" : "#/components/responses/204NoContent" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/orders" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "listOrders", "tags" : [ "Orders" ], "summary" : "Returns a list of Orders", "description" : "10 per page by default", "parameters" : [ { "$ref" : "#/components/parameters/refParam" }, { "$ref" : "#/components/parameters/filterParam" }, { "$ref" : "#/components/parameters/pageParam" }, { "$ref" : "#/components/parameters/resultsParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200OrderList" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } }, "post" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "createOrders", "tags" : [ "Orders" ], "summary" : "Inserts an array of provided Orders.", "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/OrderRequest" } } } } }, "responses" : { "201" : { "$ref" : "#/components/responses/201Order" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } }, "description" : "Create new orders." } }, "/orders/{order_id}" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "getOrder", "tags" : [ "Orders" ], "summary" : "Find an order by ID.", "parameters" : [ { "$ref" : "#/components/parameters/orderIdParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200Order" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/orders/{order_id}/transactions" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "listOrderTransactions", "tags" : [ "Orders", "Transactions" ], "summary" : "Retrieve transactions for an order.", "parameters" : [ { "$ref" : "#/components/parameters/orderIdParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200TransactionList" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/orders/{order_id}/hpp" : { "delete" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "deactivateOrderHostedPaymentPage", "tags" : [ "Orders" ], "summary" : "Deactivate the hosted payment page for an order.", "parameters" : [ { "$ref" : "#/components/parameters/orderIdParam" } ], "responses" : { "200" : { "description" : "OK" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/transactions" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "listTransactions", "tags" : [ "Transactions" ], "summary" : "Returns a list of Transactions", "description" : "10 per page by default", "parameters" : [ { "$ref" : "#/components/parameters/refParam" }, { "$ref" : "#/components/parameters/filterParam" }, { "$ref" : "#/components/parameters/pageParam" }, { "$ref" : "#/components/parameters/resultsParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200TransactionList" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } }, "post" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "createTransaction", "tags" : [ "Transactions" ], "summary" : "Submit a new Transaction", "x-docs" : { "guides" : [ { "title" : "Take a Card Payment", "href" : "/guides/v1/quick-start" }, { "title" : "Hosted Payment Pages", "href" : "/guides/v1/hosted-payment-pages" } ], "concepts" : [ { "title" : "Transactions", "href" : "/concepts/v1/transactions" } ] }, "parameters" : [ { "$ref" : "#/components/parameters/pollParam" } ], "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TransactionRequest" } } } }, "responses" : { "201" : { "description" : "created", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Transaction" } } } }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } }, "description" : "Starts a transaction by submitting a transaction request.\n\nBy default, if a response is not received from the underlying acquirer in 10 seconds, a Transaction with the state 'processing' will be returned. A polltime (milliseconds) can be supplied as a parameter, which will override the default of 10000ms.\n\nA transaction may return with the state of 'challenged'. This will require an action being taken by the user, which will result in data required by the challenge endpoint on the transaction to be resolved." } }, "/transactions/{transaction_id}" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "getTransaction", "tags" : [ "Transactions" ], "summary" : "Returns a Transaction", "description" : "Returns an identified transaction. If the transaction has not already completed processing, the request will wait a default time of 10 seconds for it to complete. If it is still not completed by the timeout, it will return in the 'processing' state. The poll time can be set using the `pollTimeMs` parameter.", "parameters" : [ { "$ref" : "#/components/parameters/pollParam" }, { "$ref" : "#/components/parameters/transactionIdParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200Transaction" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/transactions/{transaction_id}/challenge/{challenge_id}" : { "post" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "submitTransactionChallengeResponse", "tags" : [ "Transactions", "Challenges" ], "summary" : "Complete a challenge", "description" : "Submit the details required to complete a challenged transaction.", "parameters" : [ { "$ref" : "#/components/parameters/transactionIdParam" }, { "$ref" : "#/components/parameters/challengeIdParam" } ], "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ChallengeResponse" } } } }, "responses" : { "200" : { "$ref" : "#/components/responses/200Transaction" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/sessions" : { "post" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "createSession", "tags" : [ "Sessions" ], "summary" : "Start a new Session", "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SessionInput" } } } }, "responses" : { "201" : { "$ref" : "#/components/responses/201Session" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } }, "description" : "Starts a new payment session that can be used in conjunction with the Hosted Payment Fields for secure card data input.\n\nThe fields currently supported are `pan`, `expiryDate` and `securityCode`." } }, "/sessions/{session_id}" : { "get" : { "security" : [ { "accessCode" : [ "session_limited_read" ] } ], "operationId" : "getSession", "tags" : [ "Sessions" ], "summary" : "Retrieve a session", "parameters" : [ { "$ref" : "#/components/parameters/sessionIdParam" }, { "$ref" : "#/components/parameters/optionalPollParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200Session" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "403" : { "$ref" : "#/components/responses/403JWTMismatch" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } }, "description" : "Retrieves a payment session and all it's current data.\nIf a value is only required when this is updated, the parameter pollTimeMs can be used to wait for a change. If there is no change by the time the poll time is up, the unchanged Session will be returned." } }, "/sessions/{session_id}/fields/{field_name}" : { "patch" : { "security" : [ { "accessCode" : [ "session_limited_read" ] } ], "operationId" : "updateSessionField", "tags" : [ "Sessions" ], "summary" : "Update a session field", "parameters" : [ { "$ref" : "#/components/parameters/sessionIdParam" }, { "$ref" : "#/components/parameters/fieldNameParam" } ], "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SessionFieldInput" } } } }, "responses" : { "200" : { "$ref" : "#/components/responses/200Session" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "403" : { "$ref" : "#/components/responses/403JWTMismatch" }, "500" : { "$ref" : "#/components/responses/500ServerError" } }, "description" : "Allows manual updating of a payment session field." } }, "/issuers/{issuer_iin}" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "getIssuer", "tags" : [ "Issuers" ], "summary" : "Retrieve an issuer and details on whether the resulting issuer is configured to be accepted", "parameters" : [ { "$ref" : "#/components/parameters/issuerIinParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200IssuerResult" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } }, "description" : "Retrieves an issuers details based on the given IIN as well as details on whether a card with this issuer will be accepted, with the reasons for rejection." } }, "/applepay/signing-requests" : { "post" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "createApplePayCertificateSigningRequest", "tags" : [ "Apple Pay" ], "summary" : "Generate an Apple Pay Payment Processing certificate signing request", "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ApplePayCertificateSigningRequestRequest" } } } }, "responses" : { "201" : { "$ref" : "#/components/responses/201ApplePayGenerateCertificateSigningRequest" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/applepay/certificates/{certificate_signing_request_id}" : { "post" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "uploadApplePayCertificate", "tags" : [ "Apple Pay" ], "summary" : "Upload the Apple Pay Payment Processing public key certificate", "parameters" : [ { "$ref" : "#/components/parameters/certificateSigningRequestIdParam" } ], "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ApplePayPublicKeyCertificateRequest" } } } }, "responses" : { "200" : { "description" : "Successfully Uploaded" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "404" : { "$ref" : "#/components/responses/404NotFound" }, "500" : { "$ref" : "#/components/responses/500ServerError" } } } }, "/plans" : { "post" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "createPaymentPlan", "tags" : [ "Payment Plans" ], "summary" : "Create a new Payment Plan", "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PaymentPlanCreate" } } } }, "responses" : { "201" : { "$ref" : "#/components/responses/201PaymentPlan" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } }, "description" : "Created a new payment plan, as well as the initial scheduled payment associated with that payment plan" } }, "/plans/{plan_id}" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "getPaymentPlan", "tags" : [ "Payment Plans" ], "summary" : "Retrieve a payment plan", "parameters" : [ { "$ref" : "#/components/parameters/planIdParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200PaymentPlan" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } }, "description" : "Retrieves a payment plan and all its current data." }, "patch" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "updatePaymentPlan", "tags" : [ "Payment Plans" ], "summary" : "Update a payment plan", "parameters" : [ { "$ref" : "#/components/parameters/planIdParam" } ], "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PaymentPlanUpdate" } } } }, "responses" : { "200" : { "$ref" : "#/components/responses/200PaymentPlan" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } }, "description" : "Updates a payment plan\nIf the payment plan is via installments, the transaction status, retry configuration and transaction source can be updated If the payment plan is recurring, the transaction status, retry configuration, transaction source, end date, and associated order can be updated" }, "delete" : { "security" : [ { "accessCode" : [ "read", "write" ] } ], "operationId" : "deletePaymentPlan", "tags" : [ "Payment Plans" ], "summary" : "Delete a payment plan", "parameters" : [ { "$ref" : "#/components/parameters/planIdParam" } ], "responses" : { "204" : { "$ref" : "#/components/responses/204NoContent" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } }, "description" : "Deletes a payment plan" } }, "/plans/{plan_id}/payments" : { "get" : { "security" : [ { "accessCode" : [ "read" ] } ], "operationId" : "listPaymentPlanPayments", "tags" : [ "Payment Plans" ], "summary" : "Retrieve all payments associated with a payment plan", "parameters" : [ { "$ref" : "#/components/parameters/planIdParam" }, { "name" : "status", "in" : "query", "required" : false, "description" : "Filter scheduled payments by status.", "schema" : { "type" : "array", "items" : { "type" : "string" } } }, { "$ref" : "#/components/parameters/pageParam" }, { "$ref" : "#/components/parameters/resultsParam" } ], "responses" : { "200" : { "$ref" : "#/components/responses/200PaymentPlanPaymentsList" }, "400" : { "$ref" : "#/components/responses/400BadRequest" }, "500" : { "$ref" : "#/components/responses/500ServerError" } }, "description" : "Retrieves scheduled payments associated with a payment plan." } } }, "components" : { "securitySchemes" : { "accessCode" : { "type" : "oauth2", "flows" : { "clientCredentials" : { "tokenUrl" : "https://sit.encoded.services/auth/oauth", "scopes" : { "write" : "Allows modifying resources", "read" : "Allows reading resources", "session_limited_read" : "Allows updating sessions and reading session information without sensitive card information. Highly recommended to be the sole scope when using the Hosted Payment Fields javascript library." } } } } }, "responses" : { "200CustomerList" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Customer" } } } } }, "400BadRequest" : { "description" : "Bad Request", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/400Generic" } } } }, "500ServerError" : { "description" : "Server Error", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "error" : { "type" : "string", "example" : "System Error" }, "message" : { "type" : "string", "example" : "There was a system error during your request. Please try again." }, "additionalInfo" : { "type" : "object" } } } } } }, "200Customer" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Customer" } } } }, "404NotFound" : { "description" : "Not Found", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "error" : { "type" : "string", "example" : "Not Found" }, "message" : { "type" : "string", "example" : "Could not find the item with the given ID." }, "additionalInfo" : { "type" : "object" } } } } } }, "204NoContent" : { "description" : "No Content - Item successfully deleted." }, "403JWTMismatchExpressHpp" : { "description" : "Unauthorised - JWT mismatch. When generating an express hpp, the bearer token used for authorisation must have a scope of express_hpp.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "error" : { "type" : "string", "example" : "Unauthorised" }, "message" : { "type" : "string", "example" : "The bearer token used for authorisation dos not have a scope of express_hpp." }, "additionalInfo" : { "type" : "object", "example" : { } } } } } } }, "200TokenList" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Token" } } } } }, "200Token" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Token" } } } }, "400TokenMismatch" : { "description" : "Bad Request / Token Mismatch", "content" : { "application/json" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/400TokenMismatch" }, { "$ref" : "#/components/schemas/400Generic" } ] } } } }, "200OrderList" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/OrderResponse" } } } } }, "201Order" : { "description" : "Created", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/OrderResponse" } } } }, "200Order" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/OrderResponse" } } } }, "200TransactionList" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Transaction" } } } } }, "200Transaction" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Transaction" } } } }, "201Session" : { "description" : "Created session", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Session" } } } }, "200Session" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Session" } } } }, "403JWTMismatch" : { "description" : "Unauthorised - JWT mistmatch. When using a JWT with only the scope `session_limited_read` to retrieve session details, the authorisation request must contain the session ID you wish to view in the `payment_session_id` request parameter.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "error" : { "type" : "string", "example" : "Unauthorised" }, "message" : { "type" : "string", "example" : "The bearer token used for authorisation does not contain the ID of the session you are trying to access. Please ensure a new token is generated for each session, including the `payment_session_id` request parameter if you are generating tokens with session_limited_read scope exclusively.\"" }, "additionalInfo" : { "type" : "object", "example" : { } } } } } } }, "200IssuerResult" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IssuerResult" } } } }, "201ApplePayGenerateCertificateSigningRequest" : { "description" : "Generated Certificate Signing Request", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ApplePayCertificateSigningRequestResponse" } } } }, "201PaymentPlan" : { "description" : "Created payment plan", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PaymentPlan" } } } }, "200PaymentPlan" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PaymentPlan" } } } }, "200PaymentPlanPaymentsList" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/PaymentPlanPayment" } } } } } }, "parameters" : { "refParam" : { "in" : "query", "name" : "ref", "schema" : { "type" : "string" }, "required" : false, "description" : "A reference of an entity to search for. If your API configuration does not force unique entity references, there may be multiple results.", "example" : "ref-12345" }, "filterParam" : { "in" : "query", "name" : "filterParams", "schema" : { "type" : "object", "additionalProperties" : { "type" : "string" } }, "required" : false, "description" : "A way to filter the returned objects based on the attributes. In order to filter objects by an 'accountNumber' of 123456 in an 'account' attribute, you would use the parameter `filter[account.accountNumber]` with the value `123456`, e.g. `&filter[account.accountNumber]=123456`.\n\nTo search across array attributes, you would filter the same way. If you have the array 'linkedAccounts' in an 'account' attribute and are looking for an object that has the value 987654 in this array, you would use `&filter[account.linkedAccounts]=123456`", "allowReserved" : true, "examples" : { "Filter by nested account number" : { "value" : "?filter[account.accountNumber]=123456" }, "Filter by top level username" : { "value" : "?filter[username]=abcdef" }, "Filter by nested and top level attributes" : { "value" : "?filter[account.accountNumber]=123456&filter[username]=abcdef" } } }, "pageParam" : { "in" : "query", "name" : "page", "schema" : { "type" : "integer", "minimum" : 0, "default" : 0 }, "required" : false, "description" : "The page number, 0 indexed.", "example" : 3 }, "resultsParam" : { "in" : "query", "name" : "results", "schema" : { "type" : "integer", "minimum" : 1, "default" : 10 }, "required" : false, "description" : "The amount of results per page", "example" : 25 }, "customerIdParam" : { "in" : "path", "name" : "customer_id", "description" : "The ID of the customer you wish to find", "required" : true, "schema" : { "type" : "string", "format" : "uuid", "example" : "70c398b8-1e2b-4928-9326-872c566f7cde" } }, "tokenIdParam" : { "in" : "path", "name" : "token_id", "description" : "the ID of the token you wish to find.", "required" : true, "schema" : { "type" : "string", "format" : "uuid", "example" : "3a634e09-e03c-44d7-a20d-c76497664ef6" } }, "accessLevelParam" : { "in" : "path", "name" : "access_level", "description" : "The access level of the user", "required" : true, "schema" : { "type" : "string", "enum" : [ "customer", "account", "subscriber" ], "example" : "customer" } }, "orderIdParam" : { "name" : "order_id", "in" : "path", "description" : "The ID of the order you wish to find.", "required" : true, "schema" : { "type" : "string", "format" : "uuid", "example" : "70c398b8-1e2b-4928-9326-872c566f7cde" } }, "pollParam" : { "in" : "query", "name" : "pollTimeMs", "schema" : { "type" : "integer", "minimum" : 0, "default" : 30000 }, "required" : false, "description" : "The time to wait in milliseconds for an update to the requested resource before returning the resource as is.\n\nDefault is 30 seconds.", "example" : 30000 }, "transactionIdParam" : { "in" : "path", "name" : "transaction_id", "description" : "The ID of the transaction you wish to find.", "required" : true, "schema" : { "type" : "string", "format" : "uuid", "example" : "3a634e09-e03c-44d7-a20d-c76497664ef6" } }, "challengeIdParam" : { "in" : "path", "name" : "challenge_id", "description" : "The ID of the challenge to resolve.", "required" : true, "schema" : { "type" : "string", "format" : "uuid", "example" : "70c398b8-1e2b-4928-9326-872c566f7cde" } }, "sessionIdParam" : { "in" : "path", "name" : "session_id", "description" : "The ID of the session you wish to find.", "required" : true, "schema" : { "type" : "string", "format" : "uuid", "example" : "3a634e09-e03c-44d7-a20d-c76497664ef6" } }, "optionalPollParam" : { "in" : "query", "name" : "pollTimeMs", "schema" : { "type" : "integer", "minimum" : 0 }, "required" : false, "description" : "The time to wait in milliseconds for an update to the requested resource. If not specified, no polltime will be applied.", "example" : 5000 }, "fieldNameParam" : { "in" : "path", "name" : "field_name", "description" : "The name of the session field you wish to update", "required" : true, "schema" : { "type" : "string", "enum" : [ "pan", "securityCode", "expiryDate" ], "example" : "pan" } }, "issuerIinParam" : { "in" : "path", "name" : "issuer_iin", "description" : "The IIN to be looked up", "required" : true, "schema" : { "type" : "string", "format" : "iin", "example" : "535522" } }, "certificateSigningRequestIdParam" : { "in" : "path", "name" : "certificate_signing_request_id", "description" : "The ID returned by the certificate signing request.", "required" : true, "schema" : { "type" : "string", "format" : "uuid", "example" : "4fefad24-a6ce-41ba-a222-c823a31e7961" } }, "planIdParam" : { "in" : "path", "name" : "plan_id", "description" : "The ID of the plan you wish to find.", "required" : true, "schema" : { "type" : "string", "format" : "uuid", "example" : "a6c63f11-7ea7-4159-a878-d7fbaa0a8b76" } }, "applePayPublicKeyCertificateIdParam" : { "in" : "path", "name" : "public_key_certificate_id", "description" : "The ID that was supplied within the response of the certificate signing request.", "required" : true, "schema" : { "type" : "string", "format" : "uuid", "example" : "716b4bca-e8af-44b2-9dad-5eca8acf3a82" } } }, "schemas" : { "Organisation" : { "type" : "object", "description" : "A customer's organisation. On input, only the 'object' field is required, however at least one of the other fields must be populated.", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be 'organisation'.", "example" : "organisation", "pattern" : "/^(organisation)$/" }, "name" : { "type" : "string", "description" : "The organisation name.", "maxLength" : 255, "minLength" : 1, "example" : "Example, Ltd" }, "companyNumber" : { "type" : "string", "description" : "The organisation's company number.", "example" : "04329678", "maxLength" : 20, "minLength" : 1 }, "vatNumber" : { "type" : "string", "description" : "The organisation's VAT number.", "example" : "791085806", "maxLength" : 20, "minLength" : 1 } }, "additionalProperties" : false }, "Address" : { "type" : "object", "description" : "A contact's address. On input, only the 'object' field is required, however at least ONE of the following properties must be populated - forename, surname organisationName, line1, postCode, country", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be 'address'.", "example" : "address" }, "title" : { "type" : "string", "description" : "The addressee's title.", "example" : "Mr", "maxLength" : 10, "minLength" : 1 }, "forename" : { "type" : "string", "description" : "The addressee's forename.", "example" : "John", "maxLength" : 100, "minLength" : 1 }, "surname" : { "type" : "string", "description" : "The addressee's surname.", "example" : "Doe", "maxLength" : 100, "minLength" : 1 }, "organisationName" : { "type" : "string", "description" : "If an organisation address, the name of the organisation.", "example" : "Example, Ltd", "maxLength" : 100, "minLength" : 1 }, "line1" : { "type" : "string", "description" : "The 1st line of the address.", "example" : "Example House", "maxLength" : 100, "minLength" : 1 }, "line2" : { "type" : "string", "description" : "The 2nd line of the address.", "example" : "Example Street", "maxLength" : 100, "minLength" : 1 }, "line3" : { "type" : "string", "description" : "The 3rd line of the address.", "example" : "London", "maxLength" : 100, "minLength" : 1 }, "county" : { "type" : "string", "description" : "The address County.", "example" : "Greater London", "maxLength" : 100, "minLength" : 1 }, "postcode" : { "type" : "string", "description" : "The address Post Code.", "example" : "AB1 2CD", "maxLength" : 10, "minLength" : 1 }, "country" : { "type" : "string", "format" : "ISO 3166 Alpha-3", "description" : "The address country in ISO 3166 Alpha-3 format.", "example" : "GBR", "maxLength" : 3, "minLength" : 3 } }, "additionalProperties" : false }, "Phone" : { "type" : "object", "description" : "An object for the contact's phone numbers. On input, only the 'object' field is required, however at least one of the other properties must be populated.", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be 'phone'.", "example" : "phone" }, "mobile" : { "type" : "string", "description" : "The mobile telephone number.", "example" : "+447957317876", "maxLength" : 16 }, "landline" : { "type" : "string", "description" : "The landline telephone number.", "example" : "+442085756521", "maxLength" : 16 } } }, "Contact" : { "type" : "object", "description" : "A customer's contact details. On input, only the 'object' field is required, however at least ONE of the other properties must be populated.", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be 'contact'.", "example" : "contact" }, "address" : { "$ref" : "#/components/schemas/Address" }, "email" : { "type" : "string", "format" : "email", "description" : "The contact email address.", "pattern" : "^.+@.+\\..+$", "maxLength" : 100, "example" : "email@example.com" }, "phone" : { "$ref" : "#/components/schemas/Phone" } } }, "Customer" : { "description" : "A customer object. Contains information relating to a specific customer that can be used when creating orders or transactions. On creation, no fields except `object` are mandatory, but at least one other field must be populated in order to be valid.", "type" : "object", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"customer\".", "example" : "customer" }, "id" : { "type" : "string", "format" : "uuid", "readOnly" : true, "description" : "Customer ID. A Version 4 UUID generated at the time of creation." }, "creationDate" : { "type" : "string", "format" : "RFC3339", "readOnly" : true, "example" : "2019-07-01T00:00:00Z", "description" : "The creation date and time of this Customer" }, "ref" : { "type" : "string", "description" : "A reference supplied by the API user to identify this customer. The reference may be used to search for this customer. The reference is not required to be unique by default, this can be configured by your implementation manager. If not supplied, this field will be populated with the generated object ID on creation.\nThis field may be used to filter customers on a GET request.", "maxLength" : 36, "minLength" : 1, "example" : "CUST-0094637", "default" : "{customerId}" }, "title" : { "type" : "string", "description" : "The customer's title. Max 10 characters.", "maxLength" : 10, "minLength" : 1, "example" : "Mr" }, "forename" : { "type" : "string", "description" : "The customer's forename. Max 100 characters", "maxLength" : 100, "minLength" : 1, "example" : "John" }, "surname" : { "type" : "string", "description" : "The customer's surname. Max 100 characters", "maxLength" : 100, "minLength" : 1, "example" : "Doe" }, "dateOfBirth" : { "type" : "string", "format" : "yyyy-MM-dd", "description" : "The customer's date of birth. Must be yyyy-MM-dd format and in the past.", "example" : "1985-07-01" }, "organisation" : { "$ref" : "#/components/schemas/Organisation" }, "contact" : { "$ref" : "#/components/schemas/Contact" }, "attributes" : { "type" : "object", "description" : "Contains custom keys and values provided by the API user. Can accept Strings, arrays and nested objects.", "example" : { "account" : "12345", "balance" : 169.25, "aliases" : [ "Jon", "J" ], "alternativeContact" : { "workNumber" : "01234987654", "workEmail" : "work@example.com" } } }, "links" : { "type" : "object", "readOnly" : true, "description" : "The links associated with this customer.", "example" : { "self" : "./customers/96d7d98a-46fd-4d3b-a15b-b03c116ae949", "tokens" : "./customers/96d7d98a-46fd-4d3b-a15b-b03c116ae949/tokens" } } } }, "400Generic" : { "type" : "object", "properties" : { "error" : { "type" : "string", "example" : "Request data not valid" }, "message" : { "type" : "string", "example" : "object: cannot be null" }, "additionalInfo" : { "type" : "object", "example" : { "object" : "cannot be null" } } } }, "Issuer" : { "type" : "object", "description" : "An object that contains information about the issuer of a card. This will be available for cards used as a source of funds and tokens used, at retrieval.", "readOnly" : true, "properties" : { "object" : { "type" : "string", "description" : "The object type. Will only be \"issuer\"", "example" : "issuer", "readOnly" : true }, "id" : { "type" : "string", "description" : "A six digit bin number to identify this issuer.", "example" : "444433", "minLength" : 6, "maxLength" : 6, "readOnly" : true }, "scheme" : { "type" : "string", "description" : "The card scheme", "example" : "Visa", "readOnly" : true }, "type" : { "type" : "string", "description" : "The card type", "example" : "Credit", "readOnly" : true }, "level" : { "type" : "string", "description" : "The card level", "example" : "Classic", "readOnly" : true }, "brand" : { "type" : "string", "description" : "The issuer brand", "example" : "Barclays Bank Plc", "readOnly" : true }, "country" : { "type" : "string", "description" : "The issuer country (Alpha-2 Code)", "example" : "GB", "readOnly" : true } } }, "Token" : { "description" : "A Token object. Contains details about a created token.\n\nA Token object cannot be created directly, a tokenisation must be initiated during a transaction using the `tokenisation` attribute on the payment source. If a token has been successfully saved, a Token object will be available in the `transaction.response` object once the transaction has been processed.", "type" : "object", "readOnly" : true, "properties" : { "object" : { "type" : "string", "description" : "The object type. Will be \"token\".", "example" : "token" }, "id" : { "type" : "string", "format" : "uuid", "readOnly" : true, "description" : "The token ID" }, "ref" : { "type" : "string", "format" : "uuid", "readOnly" : true, "description" : "The token reference. Would have been specified as the `tokenisation` reference when making a payment with tokenisation" }, "creationDate" : { "type" : "string", "format" : "RFC3339", "readOnly" : true, "example" : "2019-07-01T00:00:00Z", "description" : "The creation date and time of this Token." }, "pan" : { "type" : "string", "readOnly" : true, "example" : "400000******0002", "description" : "The masked pan of the card tokenised." }, "expiry" : { "type" : "string", "example" : "2030-05", "description" : "The expiry date of the tokenised card." }, "securityCode" : { "type" : "string", "readOnly" : true, "example" : "***", "description" : "The masked security code of the stored card. Will indicate the length." }, "issuer" : { "$ref" : "#/components/schemas/Issuer" }, "agreement" : { "type" : "string", "description" : "The case insensitive agreement type under which this token has been stored. See `Tokenisation` for more information.", "enum" : [ "card_on_file", "recurring", "instalment", "unscheduled" ], "example" : "card_on_file" }, "billingCustomer" : { "$ref" : "#/components/schemas/Customer" }, "attributes" : { "type" : "object", "description" : "Contains custom keys and values provided by the API user in the tokenisation object when submitting a transaction request.", "example" : { "cardName" : "Business Card", "default" : true } }, "links" : { "type" : "object", "readOnly" : true, "description" : "The links associated with this token.", "example" : { "self" : "./tokens/96d7d98a-46fd-4d3b-a15b-b03c116ae949" } } } }, "400TokenMismatch" : { "type" : "object", "properties" : { "error" : { "type" : "string", "example" : "Token Mismatch" }, "message" : { "type" : "string", "example" : "This token and customer do not match. please ensure you have the correct customer and token IDs and try again." }, "additionalInfo" : { "type" : "object", "example" : { "object" : { } } } } }, "TokenInput" : { "description" : "A token input object. This will contain the data that is to be updated in a token using a PATCH request.", "type" : "object", "readOnly" : true, "properties" : { "object" : { "type" : "string", "description" : "The object type. Will be \"token\".", "example" : "token" }, "ref" : { "type" : "string", "description" : "The token reference.", "example" : "TK-123" }, "expiry" : { "type" : "string", "example" : "2030-05", "description" : "The expiry date of the tokenised card." }, "attributes" : { "type" : "object", "description" : "Contains custom keys and values provided by the API user in the tokenisation object when submitting a transaction request. due to the nature of these custom attributes, when using a PATCH request to update this property all previous data will be overwritten, so any data that is to be kept must be re-entered.", "example" : { "cardName" : "Business Card", "default" : true } } } }, "HostedPaymentPageConfigInputGooglePay" : { "type" : "object", "description" : "An object representing Google Pay configuration within Hosted Payment Pages.", "required" : [ ], "properties" : { "enabled" : { "type" : "boolean", "description" : "Whether Google Pay should be enabled for Hosted Payment Pages", "example" : true } } }, "HostedPaymentPageConfigInputApplePay" : { "type" : "object", "description" : "An object representing Apple Pay configuration within Hosted Payment Pages.", "required" : [ ], "properties" : { "enabled" : { "type" : "boolean", "description" : "Whether Apple Pay should be enabled for Hosted Payment Pages", "example" : true } } }, "HostedPaymentPageConfigInputMusqetBtc" : { "type" : "object", "description" : "An object representing Musqet Bitcoin configuration within Hosted Payment Pages.", "required" : [ ], "properties" : { "enabled" : { "type" : "boolean", "description" : "Whether Musqet Bitcoin should be enabled for Hosted Payment Pages.", "example" : true }, "businessId" : { "type" : "string", "description" : "The Musqet Business ID given by Musqet for the client.", "example" : "orics50o20001ri7o269blace" } } }, "HostedPaymentPageConfigInputLogo" : { "type" : "object", "description" : "An object representing Logo configuration within Hosted Payment Pages.", "required" : [ ], "properties" : { "data" : { "type" : "string", "description" : "The Base64 String representation of the desired logo to display.", "example" : "iVBORw0KGgo...RU5ErkJggg==" }, "format" : { "type" : "string", "enum" : [ "png", "jpeg", "webp", "svg" ], "description" : "The file format of the desired logo image file." } } }, "HostedPaymentPageConfigInputLegalNotice" : { "type" : "object", "description" : "An object representing a Legal Notice for display on the Hosted Payment Pages.", "required" : [ "name", "entity", "link" ], "properties" : { "name" : { "type" : "string", "description" : "The display name of the legal notice.", "example" : "Terms & Conditions" }, "entity" : { "type" : "string", "description" : "The display name of the legal entity for which the legal notice applies.", "example" : "Example Company Ltd" }, "link" : { "type" : "string", "description" : "The URL to the legal notice, ideally hosted on the legal entities website.", "example" : "https://exampleltd.com/legal-notices/terms-and-conditions.html" } } }, "HostedPaymentPageConfigInput" : { "description" : "The configurations for the Hosted Payment page", "type" : "object", "required" : [ ], "properties" : { "googlePay" : { "$ref" : "#/components/schemas/HostedPaymentPageConfigInputGooglePay" }, "applePay" : { "$ref" : "#/components/schemas/HostedPaymentPageConfigInputApplePay" }, "musqetBitcoin" : { "$ref" : "#/components/schemas/HostedPaymentPageConfigInputMusqetBtc" }, "defaultExpiryDuration" : { "type" : "string", "description" : "The default expiry duration for hosted payment pages", "example" : "PT10D" }, "logo" : { "$ref" : "#/components/schemas/HostedPaymentPageConfigInputLogo" }, "legalNoticeText" : { "type" : "string", "description" : "The text displayed on the hosted payment page in relation to legal notices.", "example" : "By clicking \"Pay\" you acknowledge that you have read the terms and conditions." }, "legalNotices" : { "type" : "array", "description" : "A list of legal notices to display on the Hosted Payment Pages.", "items" : { "$ref" : "#/components/schemas/HostedPaymentPageConfigInputLegalNotice" } } } }, "OrderItem" : { "description" : "An Item on an Order. On creation, no fields are required, however at least one of the following fields other than \"object\" must be populated - ref, description, quantity, unitAmount, totalAmount", "type" : "object", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"order.item\".", "example" : "order.item" }, "ref" : { "type" : "string", "description" : "A reference supplied by the API user to identify this order item. The reference is not required to be unique.", "maxLength" : 100, "minLength" : 1, "example" : "IT73278283" }, "description" : { "type" : "string", "description" : "A human readable description of the order item.", "minLength" : 1, "example" : "Part 1" }, "quantity" : { "type" : "number", "description" : "The quantity of the order item.", "example" : 2, "minimum" : 0 }, "unitAmount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The total amount of each unit of the order item. Must be greater than or qual to zero. Must have no more than 2 decimal places.", "example" : "2.40", "minimum" : 0 }, "taxUnitAmount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The tax amount of each unit of the order item. Must be greater than or qual to zero. Must have no more than 2 decimal places.", "example" : "0.40", "minimum" : 0 }, "preTaxUnitAmount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The pre-tax amount of each unit of the order item. Must be greater than or qual to zero. Must have no more than 2 decimal places.", "example" : "2.00", "minimum" : 0 }, "taxRate" : { "type" : "number", "description" : "The tax rate (as a percentage) of the order item. Useful for applying a tax rate to individual order items (especially if they have a different tax rate). Must be greater than or qual to zero. Must have no more than 2 decimal places.", "example" : 20, "minimum" : 0 }, "totalAmount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The total amount of the specified quantity of the order item. Must be greater than or qual to zero. Must have no more than 2 decimal places.", "example" : "4.80", "minimum" : 0 }, "taxAmount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The total tax amount of the specified quantity of the order item. Must be greater than or qual to zero. Must have no more than 2 decimal places.", "example" : "0.80", "minimum" : 0 }, "preTaxAmount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The total pre-tax amount of the specified quantity of the order item. Must be greater than or qual to zero. Must have no more than 2 decimal places.", "example" : "8.00", "minimum" : 0 } } }, "ReferenceCustomer" : { "description" : "A minimal reference to an existing customer. Can be used any time an identified customer is required in any parent object.", "type" : "object", "required" : [ "object", "id" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"customer\".", "example" : "customer" }, "id" : { "type" : "string", "format" : "uuid", "description" : "The customer ID. A customer with this ID must exist when using a customer reference." } } }, "Tokenisation" : { "type" : "object", "description" : "An object to hold information about the type of tokenisation to create. Providing this object as part of a source will trigger a tokenisation of the provided source details.", "required" : [ "object", "agreement" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"tokenisation\"", "example" : "tokenisation" }, "ref" : { "type" : "string", "description" : "A reference supplied by the API user to identify this token. The reference may be used to search for the resulting token. The reference is not required to be unique.", "example" : "token-1234" }, "agreement" : { "type" : "string", "description" : "The case insensitive agreement type under which this token will be stored. One of:\n\n* card_on_file -\nA transaction using a stored card for a fixed/variable amount which is not part of a scheduled/regular\nagreement but where the Cardholder themselves initiates the payment. For example, a stored card transaction\ninitiated by the cardholder directly via an E-com or IVR channel, or indirectly (by verbally authorising) via\na virtual terminal.\n\n* recurring -\nA transaction in a series of transactions processed for the purchase of goods/services provided at\nregular/fixed intervals. For example, a stored card transaction performed for an ongoing service such as\npayment towards utility bills, subscriptions, etc.\n\n* instalment -\nA transaction in a series of transactions processed over a set period and number of payments for a\nsingle purchase of goods/services. For example, a stored card transaction performed for a one-off\nservice/good, such as making monthly payments towards a large purchase.\n\n* unscheduled -\nA transaction using a stored credential for a fixed/variable amount which is not part of a\nscheduled/regular agreement but where the Cardholder has provided consent for the Merchant\nto initiate one or more future transactions. For example, a stored card transaction performed\nas a secondary means of payment when a primary means (such as Direct Debit) has failed.\n", "enum" : [ "card_on_file", "recurring", "instalment", "unscheduled" ], "example" : "card_on_file" }, "attributes" : { "type" : "object", "description" : "Additional properties to be added to the resultant token created after tokenisation.", "example" : { "cardName" : "Business Card", "default" : true } } } }, "HppTokens" : { "description" : "A Hosted Payment Page tokens object. Used to set whether tokens should be enabled on the generated payment page, and the details of any tokens generated during payment if enabled and selected. If included, both the 'enabled' and 'tokenisation' attributes must be populated.", "type" : "object", "required" : [ "enabled", "tokenisation" ], "properties" : { "enabled" : { "type" : "boolean", "description" : "If tokenisation is enabled on the payment page." }, "tokenisation" : { "description" : "The token details to be used if a token is created during payment.", "oneOf" : [ { "$ref" : "#/components/schemas/Tokenisation" } ] } } }, "DeliveryResponseItem" : { "description" : "A delivery response item object. Used to provide the user specific information about the result of the delivery attempt.", "type" : "object", "required" : [ ], "properties" : { "deliveryStatus" : { "type" : "string", "enum" : [ "sent", "delivered", "invalid_request", "error", "timeout" ], "description" : "The case insensitive type of the status of the delivery. One of:\n \n* sent -\n The delivery was successfully sent to the customer but unable to confirm that they have \n successfully received it due to the limitations of the selected delivery method.\n \n* delivered -\n The delivery was successfully sent to the customer and confirmed that they have \n successfully received it.\n \n* invalid_request -\n The delivery was not attempted due to invalid values provided within the delivery request.\n \n* error -\n The delivery was not attempted due to unexpected error occurring during the delivery \n attempt.\n \n* timeout -\n The result of the delivery could not be confirmed due to a timeout.\n", "example" : "sent" }, "message" : { "type" : "string", "description" : "An informational message about the result of the delivery attempt.", "example" : "Order sent to email address john.doe@example-email.com" }, "url" : { "type" : "string", "description" : "The URL of the link to the item that was attempted to be delivered to the customer.", "example" : "https://enc.pm/hU7e2" }, "attributes" : { "type" : "object", "readOnly" : true, "description" : "Contains custom keys and values relevant to the delivery response, notably the QR code", "example" : { "data" : "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB4bWxucz0iaHR0cDovL3d3dy", "format" : "png", "size" : 200 } } } }, "DeliveryResponse" : { "description" : "A delivery response object. Used to inform the user of the result of the delivery attempt.", "type" : "object", "required" : [ ], "properties" : { "response" : { "description" : "The configuration for delivering the item via a SMS.", "oneOf" : [ { "$ref" : "#/components/schemas/DeliveryResponseItem" } ] } } }, "HostedPaymentPageResponse" : { "description" : "A Hosted Payment Page object. Used to generate a HPP link when creating and order, and for representing the HPP details in an Order response.", "type" : "object", "required" : [ "returnUrl" ], "properties" : { "returnUrl" : { "type" : "string", "format" : "URL", "description" : "The return URL a Hosted Payment Page will be directed to after a payment result is returned." }, "tokens" : { "description" : "This object is used to set whether tokens should be enabled on the generated payment page, and the details of any tokens generated during payment if enabled and selected.", "oneOf" : [ { "$ref" : "#/components/schemas/HppTokens" } ] }, "deliveries" : { "description" : "This object is used to provide the user the results of the attempt(s) to deliver the Hosted Payment Page directly to the customer.", "items" : [ { "$ref" : "#/components/schemas/DeliveryResponse" } ], "example" : [ { "response" : { "deliveryStatus" : "sent", "message" : "Order sent to phone number 07000123456", "url" : "https://enc.pm/4RFg9" } }, { "response" : { "deliveryStatus" : "error", "message" : "Order could not be sent to email address john.doe@example-email.com", "url" : "https://enc.pm/3pU6z" } } ] }, "action" : { "type" : "string", "enum" : [ "authorise", "pay", "refund", "verify" ], "description" : "The case insensitive action that this transaction should perform. One of:\n\n* authorise -\n Performs an authorisation for the proposed transaction. A successful response from the acquirer indicates that the payment source provided is valid and that the funds are available, however no funds are transferred at this time. The acquirer may reserve the funds for a period of time. An authorisation can be captured at a later time.\n\n* pay -\n Performs an authorisation and capture in a single transaction. A successful response from the acquirer indicates that the payment source provided is valid, the funds are available, and that the funds will be moved from the payer's account to the merchant's account.\n\n* refund -\n Performs a refund of funds from the merchant's account to the payer's account. A successful response from the acquirer indicates that the funds will be moved from the merchant's account to the payer's account. When performing a refund, the _source_ may be a _Card_, _Token_, or a previously successful _Transaction_, depending on the underlying gateway provider.\n\n* verify -\n Performs a verification of the _source_. The verification method used is that which is supported by the underlying payment gateway and acquirer.\n", "example" : "pay" }, "merchantAccountId" : { "type" : "integer", "description" : "The merchant account ID that was requested to be used for processing any Hosted Payment Page transactions." } } }, "OrderResponse" : { "description" : "The base Order object. Contains all common fields between the input and output objects.", "type" : "object", "required" : [ "object", "currency", "totalAmount" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"order\".", "example" : "order" }, "id" : { "type" : "string", "format" : "uuid", "readOnly" : true, "description" : "Order ID. A Version 4 UUID generated at the time of creation." }, "creationDate" : { "type" : "string", "format" : "RFC3339", "readOnly" : true, "example" : "2019-07-01T00:00:00Z", "description" : "The creation date and time of this Order" }, "ref" : { "type" : "string", "description" : "A reference supplied by the API user to identify this order. The reference may be used to search for this order. The reference is not required to be unique by default, this can be configured by your implementation manager. If not supplied, this field will be populated with the generated object ID on creation.\nThis field may be used to filter orders on a GET request.", "maxLength" : 36, "minLength" : 1, "example" : "ORD-0372837", "default" : "{orderId}" }, "description" : { "type" : "string", "description" : "A human readable description of the order.", "minLength" : 1, "example" : "An order containing products: IT7836473, IT7843247893, IT012938" }, "currency" : { "type" : "string", "format" : "ISO4217", "description" : "The currency of the order, in ISO 4217 format.", "example" : "GBP" }, "totalAmount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The total amount of the order, including taxes. Must be greater than or equal to zero. Must have no more than 2 decimal places.", "example" : "9.60", "minimum" : 0 }, "taxAmount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The total amount of tax to be paid on the order. Must be greater than or equal to zero. Must have no more than 2 decimal places.", "example" : "1.60", "minimum" : 0 }, "preTaxAmount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The total pre-tax amount for the order. Must be greater than or qual to zero. Must have no more than 2 decimal places.", "example" : "8.00", "minimum" : 0 }, "taxRate" : { "type" : "number", "description" : "The tax rate (as a percentage) if applicable to the order as a whole. Useful for applying a tax rate when no order items have been provided. Must be greater than or qual to zero. Must have no more than 2 decimal places.", "multipleOf" : 0.01, "example" : 20, "minimum" : 0 }, "pendingAmount" : { "type" : "number", "readOnly" : true, "multipleOf" : 0.01, "description" : "The total pending amount unpaid. This field is automatically updated once a transaction is made against an order.", "example" : "9.60", "minimum" : 0 }, "items" : { "type" : "array", "description" : "A list of items in the order.", "items" : { "$ref" : "#/components/schemas/OrderItem" } }, "billingCustomer" : { "description" : "The billing customer. This address will be used as the default billing address on a Transaction if one is not specified in the Transaction Request.\n\nWhen creating an Order, a Customer can either be created here, bound to the same rules as creating a Customer using a POST request on the /customers endpoint, or a reference Customer object can be used, containing the ID of a previously created Customer.", "oneOf" : [ { "$ref" : "#/components/schemas/Customer" }, { "$ref" : "#/components/schemas/ReferenceCustomer" } ] }, "shippingCustomer" : { "description" : "The shipping customer details.\n\nWhen creating an Order, a Customer can either be created here, bound to the same rules as creating a Customer using a POST request on the /customers endpoint, or a reference Customer object can be used, containing the ID of a previously created Customer.", "oneOf" : [ { "$ref" : "#/components/schemas/Customer" }, { "$ref" : "#/components/schemas/ReferenceCustomer" } ] }, "hpp" : { "description" : "Hosted Payment Page details. When used in the request, this will generate a payment page with the options provided. The resulting payment page will be accessible using the link provided in the response Order object, at `links.hpp.v1`.\nThis object in the response serves just as reference for the details that were provided in the request and also the result(s) of the delivery attempt(s) (if they were triggered by the initial request).", "oneOf" : [ { "$ref" : "#/components/schemas/HostedPaymentPageResponse" } ] }, "attributes" : { "type" : "object", "description" : "Contains custom keys and values provided by the API user. Can accept Strings, arrays and nested objects.", "example" : { "promoName" : "SUMMER2020", "deliveryInformation" : { "safePlace" : "front_porch", "leaveWithNeighbor" : false } } }, "links" : { "type" : "object", "readOnly" : true, "description" : "The links associated with this order.", "example" : { "self" : "./orders/96d7d98a-46fd-4d3b-a15b-b03c116ae949", "hpp" : { "v1" : "./hpp/v1/96d7d98a-46fd-4d3b-a15b-b03c116ae949" } } } } }, "HppViewOrderDisplay" : { "description" : "A Hosted Payment Page order view display object. Used to configure what Order-related information will be displayed to the customer when they access the Hosted Payment Page.", "type" : "object", "required" : [ ], "properties" : { "payee" : { "type" : "boolean", "description" : "Whether information about the payee of the Order should be displayed to the customer." }, "items" : { "type" : "boolean", "description" : "Whether information about the items of the Order should be displayed to the customer." }, "totalAmount" : { "type" : "boolean", "description" : "Whether information about the total amount of the Order should be displayed to the customer." } } }, "HppViewOrderField" : { "description" : "A field to display on the Hosted Payment Page order summary bar. The field contains and name and value, both of which are displayed to the end user.", "type" : "object", "required" : [ "name", "value" ], "properties" : { "name" : { "type" : "string", "description" : "The human readable display name of the field.", "maxLength" : 100, "minLength" : 1, "example" : "Customer Name" }, "value" : { "type" : "string", "description" : "The human readable display value of the field.", "maxLength" : 100, "minLength" : 1, "example" : "Joe Bloggs" } } }, "HppViewOrder" : { "description" : "A Hosted Payment Page order view object. Used to configure the Hosted Payment Page view in terms of the Order that it is assigned to.", "type" : "object", "required" : [ ], "properties" : { "type" : { "type" : "string", "enum" : [ "minimum", "expanded" ], "description" : "The case insensitive type of Order-related view that the Hosted Payment Page should display \nto the customer. One of:\n\n* minimal -\n The default view i.e. all possible Order-related view configuration from the other objects \n are disabled.\n\n* expanded -\n The expanded view i.e. all possible Order-related view configuration from the other objects \n are enabled.\n", "example" : "minimal" }, "display" : { "description" : "The configuration for displaying certain parts of Order-specific information to the customer.", "oneOf" : [ { "$ref" : "#/components/schemas/HppViewOrderDisplay" } ] }, "fields" : { "type" : "array", "description" : "A list of displayable fields for display in the Hosted Payment Page order summary.", "items" : { "$ref" : "#/components/schemas/HppViewOrderField" } } } }, "HppViewPaymentApplePay" : { "description" : "The Apple Pay view object. Used to configure view options for Apple Pay within the Hosted Payment Page.", "type" : "object", "required" : [ ], "properties" : { "enabled" : { "type" : "boolean", "description" : "Whether to display Apple Pay within the view if available and configured." } } }, "HppViewPaymentGooglePay" : { "description" : "The Google Pay view object. Used to configure view options for Google Pay within the Hosted Payment Page.", "type" : "object", "required" : [ ], "properties" : { "enabled" : { "type" : "boolean", "description" : "Whether to display Google Pay within the view if available and configured." } } }, "HppViewPaymentMusqetBitcoin" : { "description" : "The Musqet Bitcoin view object. Used to configure view options for Musqet Bitcoin within the Hosted Payment Page.", "type" : "object", "required" : [ ], "properties" : { "enabled" : { "type" : "boolean", "description" : "Whether to display Musqet Bitcoin within the view if available and configured." } } }, "HppViewPayment" : { "description" : "A Hosted Payment Page payment view object. Used to configure the Hosted Payment Page view in terms of the payment options that are displayed within the view.", "type" : "object", "required" : [ ], "properties" : { "applePay" : { "description" : "The view configuration for Apple Pay.", "oneOf" : [ { "$ref" : "#/components/schemas/HppViewPaymentApplePay" } ] }, "googlePay" : { "description" : "The view configuration for Google Pay.", "oneOf" : [ { "$ref" : "#/components/schemas/HppViewPaymentGooglePay" } ] }, "musqetBitcoin" : { "description" : "The view configuration for Musqet Bitcoin.", "oneOf" : [ { "$ref" : "#/components/schemas/HppViewPaymentMusqetBitcoin" } ] } } }, "HppView" : { "description" : "A Hosted Payment Page view object. Used to configure what will be displayed to the customer when they access the Hosted Payment Page. If this object is not provided within the request then the default view configuration will be used.", "type" : "object", "required" : [ ], "properties" : { "theme" : { "type" : "string", "enum" : [ "classic", "modern" ], "description" : "The theme of the view. Defaults to 'modern' if not provided, unless otherwise configured." }, "order" : { "description" : "The configuration of the view involving the Order that the Hosted payment page is assigned to.", "oneOf" : [ { "$ref" : "#/components/schemas/HppViewOrder" } ] }, "payment" : { "description" : "Configuration of payment options for the view, including APM configuration.", "oneOf" : [ { "$ref" : "#/components/schemas/HppViewPayment" } ] } } }, "DeliveryRequestSms" : { "description" : "A delivery request SMS object. Used to configure the delivery of an item via an SMS.", "type" : "object", "required" : [ ], "properties" : { "mobileNumber" : { "type" : "string", "description" : "The mobile number that the SMS should be delivered to. This field can be omitted if the underlying request contains a billing customer and a mobile number was provided within it.", "example" : 7000123456 }, "alphaTag" : { "type" : "string", "description" : "The alpha tag (i.e. sender) within the delivered SMS.", "example" : "CustomerName" }, "message" : { "type" : "string", "description" : "The message within the delivered SMS.", "example" : "Please click on this link in order to pay for this order - {hpp.shortenedUrl}" } } }, "DeliveryRequestEmailBody" : { "description" : "A delivery request email body object. Used to configure the body of an email to be delivered.", "type" : "object", "required" : [ ], "properties" : { "format" : { "type" : "string", "description" : "The basic format of the body within the delivered email.", "example" : "Please click on this link in order to pay for this order - {hpp.shortenedUrl}" } } }, "DeliveryRequestEmail" : { "description" : "A delivery request email object. Used to configure the delivery of an item via an SMS.", "type" : "object", "required" : [ ], "properties" : { "sender" : { "type" : "string", "description" : "The email address where the delivered email will appear to be sent from.", "example" : "payments@example-email.com" }, "recipient" : { "type" : "string", "description" : "The email address where the delivered email will be sent to. This field can be omitted if the underlying request contains a billing customer and an email address was provided within it.", "example" : "john.doe@example-email.com" }, "subject" : { "type" : "string", "description" : "The subject of the delivered email.", "example" : "Order Payment Request" }, "body" : { "description" : "The configuration for the body of the delivery email.", "oneOf" : [ { "$ref" : "#/components/schemas/DeliveryRequestEmailBody" } ] } } }, "DeliveryRequestQr" : { "description" : "A delivery request QR object. Used to configure the delivery of an item via a QR code.", "type" : "object", "required" : [ ], "properties" : { "format" : { "type" : "string", "enum" : [ "png" ], "description" : "The file format of the QR code", "example" : "png" }, "size" : { "type" : "integer", "description" : "The size of the QR code (width and length) in pixels", "example" : 200 } } }, "OrderHostedPaymentPageDeliveryRequest" : { "description" : "A delivery request object. Used to deliver the Hosted Payment Page that can be used by a customer to pay the order assigned to it.\nThe configuration fields below use the following format keys in order to reference other fields from the underlying order:\n* {order.reference} - order reference * {order.description} - order description * {order.totalAmount} - total amount of the order * {customer.billing.mobileNumber} - the mobile number of the billing customer (if supplied within \n the underlying order)\n* {customer.billing.emailAddress} - the email address of the billing customer (if supplied within \n the underlying order)\n* {customer.shipping.mobileNumber} - the mobile number of the shipping customer (if supplied \n within the underlying order)\n* {customer.shipping.emailAddress} - the email address of the shipping customer (if supplied \n within the underlying order)\n* {hpp.shortenedUrl} - the shortened URL that is used to access the order's hosted payment page", "type" : "object", "required" : [ ], "properties" : { "sms" : { "description" : "The configuration for delivering the Hosted Payment Page via a SMS.", "oneOf" : [ { "$ref" : "#/components/schemas/DeliveryRequestSms" } ] }, "email" : { "description" : "The configuration for delivering the Hosted Payment Page via an email.", "oneOf" : [ { "$ref" : "#/components/schemas/DeliveryRequestEmail" } ] }, "qr" : { "description" : "The configuration for delivering the Hosted Payment Page via a QR code.", "oneOf" : [ { "$ref" : "#/components/schemas/DeliveryRequestQr" } ] } } }, "TypeAllowDenyList" : { "description" : "An Type Allow/Deny List object, containing the list of allowed or denied types for the card payment Either an allow or deny list can be specified, but not both.", "type" : "object", "required" : [ ], "properties" : { "allow" : { "description" : "The list of allowed types", "type" : "array", "items" : { "enum" : [ "CREDIT", "DEBIT", "CHARGE_CARD", "UNKNOWN" ] }, "example" : null }, "deny" : { "description" : "The list of denied types", "type" : "array", "items" : { "enum" : [ "CREDIT", "DEBIT", "CHARGE_CARD", "UNKNOWN" ] }, "example" : [ "CHARGE_CARD" ] } } }, "SchemeAllowDenyList" : { "description" : "An Type Allow/Deny List object, containing the list of allowed or denied schemes for the card payment Either an allow or deny list can be specified, but not both.", "type" : "object", "required" : [ ], "properties" : { "allow" : { "description" : "The list of allowed schemes", "type" : "array", "items" : { "enum" : [ "AIRPLUS", "AMERICAN_EXPRESS", "ATOS", "BANKCARD", "CHINA_UNION", "DINERS_CLUB", "DISCOVER", "FUEL_CARD", "GE_CAPITAL", "JCB", "LASER", "LOYALTY_CARD", "MAESTRO", "MASTERCARD", "PRIVATE_LABEL", "RBS_GIFT_CARD", "SOLO", "STAR_REWARDS", "VISA", "UNKNOWN" ] }, "example" : [ "VISA", "MASTERCARD" ] }, "deny" : { "description" : "The list of denied schemes", "type" : "array", "items" : { "enum" : [ "AIRPLUS", "AMERICAN_EXPRESS", "ATOS", "BANKCARD", "CHINA_UNION", "DINERS_CLUB", "DISCOVER", "FUEL_CARD", "GE_CAPITAL", "JCB", "LASER", "LOYALTY_CARD", "MAESTRO", "MASTERCARD", "PRIVATE_LABEL", "RBS_GIFT_CARD", "SOLO", "STAR_REWARDS", "VISA", "UNKNOWN" ] }, "example" : null } } }, "HppIssuer" : { "description" : "A Hosted Payment Page issuer object, which contains the card specific data for the hosted payment page", "type" : "object", "required" : [ ], "properties" : { "type" : { "description" : "This object contains the list of allowed or denied types for the card payment", "oneOf" : [ { "$ref" : "#/components/schemas/TypeAllowDenyList" } ] }, "scheme" : { "description" : "This object contains the list of allowed or denied schemes for the card payment", "oneOf" : [ { "$ref" : "#/components/schemas/SchemeAllowDenyList" } ] } } }, "HppCard" : { "description" : "A Hosted Payment Page card object, which contains the card specific data for the hosted payment page", "type" : "object", "required" : [ ], "properties" : { "issuer" : { "description" : "This object contains the issuer specific data for the hpp transaction", "oneOf" : [ { "$ref" : "#/components/schemas/HppIssuer" } ] } } }, "HppTransaction" : { "description" : "A Hosted Payment Page transaction object, which contains the card specific data for the hosted payment page", "type" : "object", "required" : [ ], "properties" : { "card" : { "description" : "This object contains the card specific data for the hpp transaction", "oneOf" : [ { "$ref" : "#/components/schemas/HppCard" } ] } } }, "OrderHostedPaymentPageRequest" : { "description" : "A Hosted Payment Page object. Used to generate a HPP link when creating an order, and for representing the HPP details in an Order response.", "type" : "object", "required" : [ ], "properties" : { "returnUrl" : { "type" : "string", "format" : "URL", "description" : "The return URL a Hosted Payment Page will be directed to after a payment result is returned. If no value is provided then the whole customer flow will be contained within the Hosted Payment Page web application i.e. accepted transactions will show a transaction result view informing the customer of the details of the successful authorisation e.g. authorisation code." }, "tokens" : { "description" : "This object is used to set whether tokens should be enabled on the generated payment page, and the details of any tokens generated during payment if enabled and selected.", "oneOf" : [ { "$ref" : "#/components/schemas/HppTokens" } ] }, "view" : { "description" : "This object is used to set what information gets displayed to the customer when using the Hosted Payment Page.", "oneOf" : [ { "$ref" : "#/components/schemas/HppView" } ] }, "delivery" : { "description" : "This object is used to set whether the Hosted Payment Page should be delivered directly to the customer and how it will be sent to them.", "oneOf" : [ { "$ref" : "#/components/schemas/OrderHostedPaymentPageDeliveryRequest" } ] }, "action" : { "type" : "string", "enum" : [ "authorise", "pay", "refund", "verify" ], "description" : "The case insensitive action that this transaction should perform. One of:\n\n* authorise -\n Performs an authorisation for the proposed transaction. A successful response from the acquirer indicates that the payment source provided is valid and that the funds are available, however no funds are transferred at this time. The acquirer may reserve the funds for a period of time. An authorisation can be captured at a later time.\n\n* pay -\n Performs an authorisation and capture in a single transaction. A successful response from the acquirer indicates that the payment source provided is valid, the funds are available, and that the funds will be moved from the payer's account to the merchant's account.\n\n* refund -\n Performs a refund of funds from the merchant's account to the payer's account. A successful response from the acquirer indicates that the funds will be moved from the merchant's account to the payer's account. When performing a refund, the _source_ may be a _Card_, _Token_, or a previously successful _Transaction_, depending on the underlying gateway provider.\n\n* verify -\n Performs a verification of the _source_. The verification method used is that which is supported by the underlying payment gateway and acquirer.\n", "example" : "pay" }, "transaction" : { "description" : "This object contains the transaction specific data for the hosted payment page", "oneOf" : [ { "$ref" : "#/components/schemas/HppTransaction" } ] }, "merchantAccountId" : { "type" : "integer", "description" : "Explicitly sets the merchant account ID to use for processing any Hosted Payment Page transactions. Overrides any automated selection of underlying merchant accounts. Please speak to your Implementations Manager if you wish to use this option." } } }, "OrderRequest" : { "description" : "The base Order object. Contains all common fields between the input and output objects.", "type" : "object", "required" : [ "object", "currency", "totalAmount" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"order\".", "example" : "order" }, "id" : { "type" : "string", "format" : "uuid", "readOnly" : true, "description" : "Order ID. A Version 4 UUID generated at the time of creation." }, "creationDate" : { "type" : "string", "format" : "RFC3339", "readOnly" : true, "example" : "2019-07-01T00:00:00Z", "description" : "The creation date and time of this Order" }, "ref" : { "type" : "string", "description" : "A reference supplied by the API user to identify this order. The reference may be used to search for this order. The reference is not required to be unique by default, this can be configured by your implementation manager. If not supplied, this field will be populated with the generated object ID on creation.\nThis field may be used to filter orders on a GET request.", "maxLength" : 36, "minLength" : 1, "example" : "ORD-0372837", "default" : "{orderId}" }, "description" : { "type" : "string", "description" : "A human readable description of the order.", "minLength" : 1, "example" : "An order containing products: IT7836473, IT7843247893, IT012938" }, "currency" : { "type" : "string", "format" : "ISO4217", "description" : "The currency of the order, in ISO 4217 format.", "example" : "GBP" }, "totalAmount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The total amount of the order, including taxes. Must be greater than or equal to zero. Must have no more than 2 decimal places.", "example" : "9.60", "minimum" : 0 }, "taxAmount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The total amount of tax to be paid on the order. Must be greater than or equal to zero. Must have no more than 2 decimal places.", "example" : "1.60", "minimum" : 0 }, "preTaxAmount" : { "type" : "number", "multipleOf" : 0.01, "description" : "The total pre-tax amount for the order. Must be greater than or qual to zero. Must have no more than 2 decimal places.", "example" : "8.00", "minimum" : 0 }, "taxRate" : { "type" : "number", "description" : "The tax rate (as a percentage) if applicable to the order as a whole. Useful for applying a tax rate when no order items have been provided. Must be greater than or qual to zero. Must have no more than 2 decimal places.", "multipleOf" : 0.01, "example" : 20, "minimum" : 0 }, "pendingAmount" : { "type" : "number", "readOnly" : true, "multipleOf" : 0.01, "description" : "The total pending amount unpaid. This field is automatically updated once a transaction is made against an order.", "example" : "9.60", "minimum" : 0 }, "items" : { "type" : "array", "description" : "A list of items in the order.", "items" : { "$ref" : "#/components/schemas/OrderItem" } }, "billingCustomer" : { "description" : "The billing customer. This address will be used as the default billing address on a Transaction if one is not specified in the Transaction Request.\n\nWhen creating an Order, a Customer can either be created here, bound to the same rules as creating a Customer using a POST request on the /customers endpoint, or a reference Customer object can be used, containing the ID of a previously created Customer.", "oneOf" : [ { "$ref" : "#/components/schemas/Customer" }, { "$ref" : "#/components/schemas/ReferenceCustomer" } ] }, "shippingCustomer" : { "description" : "The shipping customer details.\n\nWhen creating an Order, a Customer can either be created here, bound to the same rules as creating a Customer using a POST request on the /customers endpoint, or a reference Customer object can be used, containing the ID of a previously created Customer.", "oneOf" : [ { "$ref" : "#/components/schemas/Customer" }, { "$ref" : "#/components/schemas/ReferenceCustomer" } ] }, "hpp" : { "description" : "Hosted Payment Page details. When used in the request, this will generate a payment page with the options provided. The resulting payment page will be accessible using the link provided in the response Order object, at `links.hpp.v1`.\nThis object in the response serves just as reference for the details that were provided in the request and also the result(s) of the delivery attempt(s) (if they were triggered by the initial request).", "oneOf" : [ { "$ref" : "#/components/schemas/OrderHostedPaymentPageRequest" } ] }, "attributes" : { "type" : "object", "description" : "Contains custom keys and values provided by the API user. Can accept Strings, arrays and nested objects.", "example" : { "promoName" : "SUMMER2020", "deliveryInformation" : { "safePlace" : "front_porch", "leaveWithNeighbor" : false } } }, "links" : { "type" : "object", "readOnly" : true, "description" : "The links associated with this order.", "example" : { "self" : "./orders/96d7d98a-46fd-4d3b-a15b-b03c116ae949", "hpp" : { "v1" : "./hpp/v1/96d7d98a-46fd-4d3b-a15b-b03c116ae949" } } } } }, "ReferenceOrder" : { "description" : "A minimal reference to an existing order. Can be used any time an identified order is required in any parent object.", "type" : "object", "required" : [ "object", "id" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"order\".", "example" : "order" }, "id" : { "type" : "string", "format" : "uuid", "description" : "The order ID. A order with this ID must exist when using a order reference." } } }, "Card" : { "type" : "object", "description" : "An object containing card details", "required" : [ "object", "pan", "expiry" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"card\".", "example" : "card" }, "pan" : { "type" : "string", "description" : "The long number on the front of the card. This will be masked when the object is retrieved.", "example" : "4444333322221111", "minLength" : 12, "maxLength" : 19 }, "expiry" : { "type" : "string", "format" : "yyyy-MM", "description" : "The card's expiry date, as an ISO 8601 year-month value in the format YYYY-MM.", "example" : "2020-05" }, "securityCode" : { "type" : "string", "description" : "The card's security code, either 3 or 4 digits depending on the card issuer. This will be masked when the object is retrieved.", "example" : "111", "minLength" : 3, "maxLength" : 4 }, "issuer" : { "$ref" : "#/components/schemas/Issuer" }, "tokenisation" : { "$ref" : "#/components/schemas/Tokenisation" } } }, "TokenReference" : { "description" : "A Token reference. May be used to reference a token as a transaction source.", "type" : "object", "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"token\".", "example" : "token" }, "id" : { "type" : "string", "format" : "uuid", "description" : "The token ID. A token with this ID must exist when using a token reference." } } }, "TransactionReference" : { "description" : "A reference transaction object.", "type" : "object", "required" : [ "object", "id" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"transaction\".", "example" : "transaction" }, "id" : { "type" : "string", "format" : "uuid", "description" : "A unique ID for this transaction. A version 4 UUID generated at time of creation.", "example" : "4b502950-8801-4112-ba15-88f8eb280525" } } }, "SessionReference" : { "description" : "A reference to a previously created `session` object. May be used when referencing a session as a payment source in a `transaction`", "type" : "object", "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"session\".", "example" : "session" }, "id" : { "type" : "string", "format" : "uuid", "description" : "The ID of the referenced session." }, "tokenisation" : { "$ref" : "#/components/schemas/Tokenisation" } } }, "GooglePayInput" : { "type" : "object", "description" : "An object representing a Google Pay transaction source prior to a transaction being processed. This will contain the encrypted payment token provided by the Google Pay web/android system.", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be 'google_pay'.", "example" : "google_pay", "pattern" : "/^(google_pay)$/" }, "token" : { "type" : "string", "description" : "The payment token for the Google Pay payment, encoded in Base64", "example" : "ewogICJwcm90b2NvbFZlcnNpb24iOiJFQ3YyIiwKICAic2lnbmF0dXJlIjoiTUVRQ0lINlE0T3dRMGpBY2VGRWtHRjBKSUQ2c0pOWHhPRWk0cittQTdiaVJ4cUJRQWlBb25kcW9VcFUvYmRzckFPcFpJc3JIUVM5bndpaU53T3JyMjRSeVBlSEEwUVx1MDAzZFx1MDAzZCIsCiAgImludGVybWVkaWF0ZVNpZ25pbmdLZXkiOnsKICAgICJzaWduZWRLZXkiOiAie1wia2V5RXhwaXJhdGlvblwiOlwiMTU0MjMyMzM5MzE0N1wiLFwia2V5VmFsdWVcIjpcIk1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRS8xKzNIQlZTYmR2K2o3TmFBcmRnTXlvU0FNNDN5UnlkenFkZzFUeG9kU3pBOTZEajRNYzFFaUtyb3h4dW5hdlZJdmR4R25KZUZWaVR6RnZ6RlJ4eUN3XFx1MDAzZFxcdTAwM2RcIn0iLAogICAgInNpZ25hdHVyZXMiOiBbIk1FWUNJUUNPMkVJaTQ4czhWVEgraWxNRXBvWExGZmt4QXdIamZQU0NWRUQvUURTSG1RSWhBTExKbXJVbE5BWThoRFFSVi95MWlLWkdzV3BlTm1JUCt6K3RDUUhReFAwdiJdCiAgfSwKICAic2lnbmVkTWVzc2FnZSI6IntcInRhZ1wiOlwianBHejFGMUJjb2kvZkNOeEk5bjdRcnN3N2k3S0hyR3RUZjNOclJjbHQrVVxcdTAwM2RcIixcImVwaGVtZXJhbFB1YmxpY0tleVwiOlwiQkphdHlGdkZQUEQyMWw4L3VMUDQ2VGExaHNLSG5kZjhaK3RBZ2srREVQUWdZVGtoSHkxOWNGM2gvYlhzMHRXVG1adG5ObSt2bFZyS2JSVTlLOCs3Y1pzXFx1MDAzZFwiLFwiZW5jcnlwdGVkTWVzc2FnZVwiOlwibUtPb1h3aThPYXZaXCJ9Igp9" }, "tokenisation" : { "oneOf" : [ { "$ref" : "#/components/schemas/Tokenisation" } ] } }, "additionalProperties" : false }, "GooglePayPayment" : { "type" : "object", "description" : "An object containing the underlying information contained within the encrypted payment token provided by the Google Pay web/android system. This will represent the details of the underlying card information used to process the transaction.", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be 'google_pay_payment'.", "example" : "google_pay_payment", "pattern" : "/^(google_pay_payment)$/" }, "transactionId" : { "type" : "string", "format" : "uuid", "description" : "The transaction identifier that Google provided when the customer authorised the transaction", "example" : "f7ed0f8f-0923-4eed-84ce-45351620bb1a", "readOnly" : true }, "paymentMethod" : { "type" : "string", "enum" : [ "payment_card" ], "description" : "The type of source that supports the provided Google Pay token.", "readOnly" : true }, "authenticationMethod" : { "type" : "string", "enum" : [ "3ds_cryptogram", "pan_only" ], "description" : "The authentication method for the google pay payment", "readOnly" : true }, "card" : { "description" : "An object containing card details. Null if the payment method isn't by card", "oneOf" : [ { "$ref" : "#/components/schemas/Card" } ], "readOnly" : true } } }, "GooglePayOutput" : { "type" : "object", "description" : "An object representing a Google Pay transaction source once a transaction has been processed. This will contain an object detailing the underlying payment card details.", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be 'google_pay'.", "example" : "google_pay", "pattern" : "/^(google_pay)$/" }, "googlePayPayment" : { "oneOf" : [ { "$ref" : "#/components/schemas/GooglePayPayment" } ] } }, "additionalProperties" : false }, "ApplePayInput" : { "type" : "object", "description" : "An object representing an Apple Pay transaction source prior to a transaction being processed. This will contain the full JSON which contains the encrypted payment token provided by the Apple Pay JavaScript API.", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be 'apple_pay'.", "example" : "apple_pay", "pattern" : "/^(apple_pay)$/" }, "token" : { "type" : "string", "description" : "The full JSON (encoded in Base64) that is returned by the Apple Pay JavaScript API after a customer authorises a transaction using their iOS device (e.g. using version 14 - the payment object returned within the onpaymentauthorized event of a generated and validated Apple Pay Session).", "example" : "eyJwYXltZW50RGF0YSI6eyJkYXRhIjoicmQ1U0pCTnpBZTladjZNYmNBeGhGYXVONXRBUm11ZVpHRWduNjkxeG0yNDM0cGdpRDR3M1hkNDVqckQ4MCtSZ1BGTTZVMG1MZlJBTU5EZ1pxYzY4V1kySjhlUFdLTlYycXQzMUxSLzBDUXRMZ01wWkNqN24yTjRjRjR3eEpRTkU0UE44NGlBcHFDSzZLSFlKRU1IZ1ZHUUhIRERoSGptd3ZlWlJiemdFWHQwWlM0RndkaFpiUXVrNEFMamV0RzR0dDRUTFd6WXBSalB6M3VFamEzSDBnVjJyemMyTlFRSzBFNjc1dWNpaXZDQTd3Z3oyNFMxaWVUdVdTZ0RqTFpwWldhTUgxLzdBa0NmVVhGQlNtY3ZkdzhiUVJCWjl1RWZEbllYNkxRZHBCeTlpN1lNbUVuWHhodmlTUjN4a2M1N2JVYkhYK1FRM005cXJERzduZFIzeGpReWRxNzdQVGNOd2I3VHlHcjNyTUV6VU5wQ0M2dkIzZ1M3WEJycEtjQkQxZ3dtazJnZVV1QVpqekJMPSIsInNpZ25hdHVyZSI6IndKUDlQZlI3RVB2cnUxQmt5ZTdpdjR4MnhoMEpaU0dmZDZqQnJVYmFVNUN2WGdSSHp3MndkZ3FNS1dDNDh3cDVHUkJWbXYyMkRONEw3Wks2anQweWNMMEJ4alljYjZKOVFZYlA3ZGZHdnY3REVjanp0Y1hoR1hmWDVuZHZYRzF5cEh6aEs1dG16eHoyaWY1R1Vxbk52YjNFazlQQkE2UjVqcEIwYk5TQVcwYWFEaXd0dHhFUGFNTmpIREdVeXFORmpVVnoybkdBMXdiTFJyMTZLWnhLU0xBbkYwdHRCMVRiMjViWUJQM1Fia0RKTlphVnJESkxLOXlQTG04ajFNQ0JjYUptVFBWR1RiYWFaZ1J1ZHBiMk1lWHpNN2Q0YmRXNloxZ2dhVU5uVDY1VjZjd2hqUDhrMDZSTEtoNy96ZktuTDgxakZhYjM0aXJ3dmpBcVUySlh6aXc4dmphQ2ttTTg1ZTk4N0xLRVdZVUtxTHA0cE5YakRhWkRLRHFtVHpGZHpMUTFTaDVuTG5MVHQ5SzY2d1hHVWhOOG1jWWhNaUtYcHJlQmJabTA3ak1QV0Y4N1VWd3FZWk5ZUFhWV2NCSmc1N2REVlR1anQ2WlJXamc2NktGZjVXeHZxd3lkOVJndmVubTJDUVl1dXdGY25RUkcxV1IyaDJQUHVHS1lhOWZad0xNYnJnRzQyaWRISlgwYTNSN2g2eTZHdm5Rd0ZQWG1LYWJtanBrNXhCRDBWMzBVY2dWVkpoaThYckZxeEpOU3ZOUjFwUFR0RDRjWHdRcGhjRUxqRHk2OHlqTlV4U0pqMHhScVhWUnFnMlU3MWgydHdwd2I5OVduYnA5dU51TWNXUStEdlFGbmhFSlZ5Zm1SZVJrYmJlZVVGS2dIZUtOcllHMEE4WTJNYWpBSFlDR0xxRmlGbjZXVDFWSlpOSzlCdzZESHl3a21pWGppWEw0dEVmQmhkM0ZHUHdrNEZ5SFYyTEp3OTZhNTAzNTFSTkVaS2F1THJZSlpXd3RmanhRMVIzV3l5NG5BNFFjeXFxVFF1NkwyRDFSTGpMMFpnNktyYVRyRlpIaUtHQTZmNzR5ZWgrazczWnBkeE42aGFNSHBwaVlYSmltVTMzdWRmbnRwa3lVY1hIdFM4VHAwUjVDVXVkQldrS3I0dlhudEUxTXlUUnZ5ZFhIUUswUWVVOWNmME1lZFI3Vzg1djJkdGFoSFpwdDFLMEtTVDRMckRBckZINnE0Z3V6WEUyZDFZQzdUSjFabTBVY2ZYR0NaNmtKZDRDOTlBZnd6VGthTnZtWlBEdmlMQ3VoSjFRWTd3RktQTVZaS1lKWHlCdU5rQ0V5R2ZIdTN3ZnRqTFdXeStjWmRlNDZHSEh3NXk2RjFxYURmSmdZa1dSZ0hCMk1XNGF3eDJGN1hXMVk1ZmRGN1NGYVJ5ZlJZWlFnZVozU01EUlFkUU1FY2R0TFMzM253cndNbWV0YjkzQ0RXV0VKR0FBdnhBSkJhQXpBYk01WDhBRzY2aEc0dkJxV1MzRTU2SkNVSG5CdWRIakRKa1hyNlRiWE5raGtUaUV4QlhQamNiNmE4VDRqVDJiM05ISkFuOVNxYnc2NERtZnYxS2I4Rk5iRXRZSjg1d0w4ZEJnMjlYaDRQTkpNZmlRS2kxS2NNSzRCN25tWnRXTXprSjl0d2VlZ01FeHdMVWdqRjZMOS8zeEE0Zk4xR1ZjU3dKbnVyVWJHbTNDUkNHaWRwR2I3R3VYWHc3ejNTUkJwNGQ3NVdHa1p2U2lmMlRReGZpZlVKQzFXYk1XTm0xOHUycGVSMXV1SjA4bnhEamZjRHRyR1cwOEZickxYeVpGTEx2MUxLcTg1VDUzUStiQzFVcTR3ZXlRR0Fya2RjS0o5R1FkRHZZUGcwa2hWa0FpNkt0eFBuZ2ZXbld1MWJ1cmhURVViVzVqM1pxdE5CalhwTDVObldkanhpRXZEVmUwYzNHbmdmalUzUXo5MUozak1mTVNxTTNZTU1Wam5SRUhUa0s1aEt0SFR1dFNmVENCM0p1UEJ1UFRQZk1CeFVDZlEyUERkTFRETmU4TEw0enduNnYxRm1UeGZ2ODBNOENTNVJOVGdERThZMDUydFk1VzRSS2EzdjBjOTVDME5VY0JlaE15RzFyd1Y5SldWekJqWVM4N1dLZTAxTjZ4RmNpSFRpVXh1ZXR0S1A4VWF2V1Y4NUQwVjFrWFVGRUFhQzNiTlA5WlZ5eFhNbXY0MUpOSjB0OUhndUNWQlVwZ25oMTZOWW12RGVXa2V1WWNDWVRZNmQ2VjRqYVMzakVIdC92U0ZoMnBIWWJGZ3l6UWJZVUZndDVoNVFQU3E1WW1oRWVMQ2dlMzBCYlNiQTBjbkxCbTAzbU42bXA2VDZXYkFxcjgyY2p5REhrN0hCYndObnJIcjBCcTNBTmt0M3htdnpCTDV3M1lZTEpoaXJVeko3MWprWTRkYmpyU3A3WEpxZjBrdjMzalBTeDFqbXlhNGtKTEYwaFJtMkZHN21UeDB2SmttcVJNQTVCeXBkWVgrcnhlUWJCVHA0RTYyNENWaEREUWlMeGhFajlEVDJxeDZUZWhpSERGSmYzTVFTUnFhaWpkUWg4ZU1KSEdwV1NHdWFOeW5xN0V2S3VtVVFoeXdTanlNelp2M0dUZkJxSmllTEhOR3lqanVXUTA3NGFpeWdUVFNNeWc5WWJWUVh6ZEt6TU5QeUxmY0cxSGNxYXpiZTYwZmJuOVE5VERHZzdTWlJ5eWRGUU01UHVNQmI5M1VCTmh5ZnVxcHdTZnZTbnRONjE5Q1NRMlhMcUN6QXcrQkNLeFI3a1FyWmtRMVhBWmRuWXF0OFJUWmRmNFdGbURDa0FlZjFRbUVYaHcyTlBCdUdiZ1pNSGhXdWF4TVRyeUpSYmJROGROWXhpdU5nOGRHRUhRcHFBWFNGRUxkNGdCMzU4UlZ0RVBlS2VnQWdlTHlSWFVodjh6NFRTNjJoVEF3SjBWdXZlNE00RDB2ZzVLSGd0WGcyMTNUR1RmUmlZVTNnZUJ1U1NTbnlMUkxucTNSM1FLdDdEOHh0UW1RVGI1SkptVzNuTVpKUHcwR0w2dzM0TG1nZ0JUclo5eGRkYXROWTVmRkJKRzFNR1VBenZ3Q2pkOHpFUlg5VnZYcmgyNnhZZExTRnROTksxTmZiZGVGVmVhVExSdzJlbmZScUVFZDdTTWVrRFdkYVcwWGJlVWZiOXk5N0hrNjBVNk52RWV0aURqcm1wcXpuWWZFemJwbk5xald5aFlOZHloR0d6YUplWlRteXU0ajBieUJLRHdONGVLRVNXaWZnMTRjZzkxWTV4djQzM0w3NU1RS2N6MTAvV3dpTVQzUFc4ZDlZVkRjTW1qZDczMnlOMjUyRktqdGpWamdUWTkvZ3JHWUhoQ2o4dEFNWnVSSnVXblVaMnUydUFxNjM3RXBEdkJZazN2amhGUHpNem5XbmpoeFc3d3pFNFRnRk44OEN1ZzUwbWRlS0plNUVITHB2eGZmS015MTJNaWlBSzMwV2ZxVmtMRGRIMTl5ZkFoMTNnLzNnS0J1MkZDZmh5NmpXQ0dMTDdKTHFndnJaZUR3bThyVnpNNkFyMVJ3NmNNank3QzlTWjBhSFFGcVFIdTVMV3RlWVVERzJBVTdTUFlYUDVZQmEzZzRjTDlEbnJjaVd0NlhMdENOQTY4ZzBlTjZBaU5CZ2J5ZTB6OFhNejZESkExNW1iVGhxUDZmV2pxYmU4OFowU0JZdW0wWHlOWFFiODBwMmZCcTJXY1N2Q0taYUxndWlOSFNrVmF1NVNTQXFLYkFyZTRBY1V6dXQwQkdpMVh2NDh2YjZXeDZTQ2YxQ1IwMjFOeVhSNGNoRDQ3Sm1HWXIzSkdEZDdUSlViRHZBWkQwSEVneEdQaXQxV0s1MkpCWlVqMWI9IiwiaGVhZGVyIjp7InB1YmxpY0tleUhhc2giOiJSQWZZS3ZLQ1ZWUzEzdVlNMVk4MzR5UWduazY0ZEx3RXVOaHhlNEV5U0tLPSIsImVwaGVtZXJhbFB1YmxpY0tleSI6Ill0MnRLMEd6S0VGeDZoOGNZa0p1RVErKzVIRE10Ujd3WVFOUENSN0pRdDJKSi9ORHRLZlNuU0w3dUQ4MlRoWGNXd3dIRVhuZmN1ZHFXVloxNEJjVzdtTjhHRTFoR0dibkUybnZVOUpuZm16cUFYVjFtdDNQREo2dks3PT0iLCJ0cmFuc2FjdGlvbklkIjoiNTY1YTUwOTcxMzFmMzViZDIwYmQ0OWY1MDdkYTg5NzA2ODJlMmQ3ZGJiNzIwZTE3MDkwZWNkMzBlYTI5Y2FhNCJ9LCJ2ZXJzaW9uIjoiRUNfdjEifSwicGF5bWVudE1ldGhvZCI6eyJkaXNwbGF5TmFtZSI6IkFtRXggMjg0NiIsIm5ldHdvcmsiOiJBbUV4IiwidHlwZSI6ImNyZWRpdCJ9LCJ0cmFuc2FjdGlvbklkZW50aWZpZXIiOiI1NjVBNTA5NzEzMUYzNUJEMjBCRDQ5RjUwN0RBODk3MDY4MkUyRDdEQkI3MjBFMTcwOTBFQ0QzMEVBMjlDQUE0In0=" }, "tokenisation" : { "oneOf" : [ { "$ref" : "#/components/schemas/Tokenisation" } ] } }, "additionalProperties" : false }, "ApplePayPayment" : { "type" : "object", "description" : "An object containing the underlying information contained within the encrypted payment token provided by the Apple Pay iOS system. This will represent the details of the underlying card information used to process the transaction.", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be 'apple_pay_payment'.", "example" : "apple_pay_payment", "pattern" : "/^(apple_pay_payment)$/" }, "transactionId" : { "type" : "string", "format" : "uuid", "description" : "The transaction identifier that Apple provided when the customer authorised the transaction (i.e. within the initial JSON that was sent to us).", "example" : "565a5097131f35bd20bd49f507da8970682e2d7dbb720e17090ecd30ea29caa4", "readOnly" : true }, "underlyingSource" : { "type" : "string", "enum" : [ "payment_card" ], "description" : "The type of source that supports the provided Apple Pay token.", "readOnly" : true }, "authenticationMethod" : { "type" : "string", "enum" : [ "3ds_cryptogram" ], "description" : "The authentication method for the apple pay payment", "readOnly" : true }, "card" : { "description" : "An object containing card details. Null if the payment method isn't by card", "oneOf" : [ { "$ref" : "#/components/schemas/Card" } ], "readOnly" : true } } }, "ApplePayOutput" : { "type" : "object", "description" : "An object representing a Apple Pay transaction source once a transaction has been processed. This will contain an object detailing the underlying payment card details.", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be 'apple_pay'.", "example" : "apple_pay", "pattern" : "/^(apple_pay)$/" }, "applePayPayment" : { "oneOf" : [ { "$ref" : "#/components/schemas/ApplePayPayment" } ] } }, "additionalProperties" : false }, "MusqetBtcInput" : { "description" : "An object containing the results of a Musqet Bitcoin transaction.", "type" : "object", "required" : [ "businessId" ], "properties" : { "object" : { "type" : "string", "description" : "the object type. Must be \"musqet_btc\"", "example" : "musqet_btc" }, "businessId" : { "type" : "string", "description" : "The Musqet Business ID given by Musqet for the client.", "example" : "orics50o20001ri7o269blace" } } }, "MusqetBtcOutput" : { "description" : "An object containing the results of a Musqet Bitcoin transaction.", "type" : "object", "required" : [ "businessId", "checkoutId" ], "properties" : { "object" : { "type" : "string", "description" : "the object type. Must be \"musqet_btc\"", "example" : "musqet_btc" }, "businessId" : { "type" : "string", "description" : "The Musqet Business ID given by Musqet for the client.", "example" : "orics50o20001ri7o269blace" }, "checkoutId" : { "type" : "string", "description" : "The checkout ID given by musqet for the completed transaction.", "example" : "001d0fb7-ab81-43fa-8174-960cb49cc7f9" } } }, "NetworkTokenInput" : { "type" : "object", "description" : "An object representing a Network Token transaction source prior to a transaction being processed. This will contain the encrypted payment token provided by the Google Pay web/android system.", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be 'network_token'.", "example" : "network_token", "pattern" : "/^(network_token)$/" }, "token" : { "type" : "string", "description" : "The payment token for the Network Token payment" }, "cryptogram" : { "type" : "string", "description" : "The cryptogram to support the Network Token, encoded in Base64.", "example" : "AVCXZwX91aMaABOZyASDFQWERD==" }, "bin" : { "type" : "string", "description" : "The BIN for the payment card used." }, "lastFour" : { "type" : "string", "description" : "The last four digits of the payment card used." }, "expiry" : { "type" : "string", "format" : "yyyy-MM", "description" : "The card's expiry date, as an ISO 8601 year-month value in the format YYYY-MM.", "example" : "2026-05" }, "eci" : { "type" : "string", "description" : "The eci value received from the 3D Secure provider once the customer's authentication has been completed. Normally a string comprised of 2 digits with a leading zero.", "example" : 5 }, "tokenSupplier" : { "type" : "string", "description" : "Identifies the supplier of the token. Either Mastercard or Visa.", "example" : "mastercard" }, "source" : { "type" : "string", "description" : "Identifies where the token came from.", "example" : "clicktopay" } }, "additionalProperties" : false }, "NetworkTokenOutput" : { "type" : "object", "description" : "An object representing a Network Token transaction source prior to a transaction being processed. This will contain an object detailing the underlying payment card details.", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be 'network_token'.", "example" : "network_token", "pattern" : "/^(network_token)$/" }, "networkTokenId" : { "type" : "string", "description" : "The ID for the Network Token payment, a UUID." }, "token" : { "type" : "string", "description" : "The payment token for the Network Token payment" }, "card" : { "$ref" : "#/components/schemas/Card" }, "eci" : { "type" : "string", "description" : "The eci value received from the 3D Secure provider once the customer's authentication has been completed. Normally a string comprised of 2 digits with a leading zero.", "example" : 5 }, "tokenSupplier" : { "type" : "string", "description" : "Identifies the supplier of the token. Either Mastercard or Visa.", "example" : "mastercard" }, "source" : { "type" : "string", "description" : "Identifies where the token came from.", "example" : "clicktopay" } }, "additionalProperties" : false }, "Source" : { "type" : "object", "description" : "An object that contains the source of funds for a transaction request. Requires one type of source to be set (one of _card_, _token_, _transaction_ or _session_).", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"source\".", "example" : "source" }, "card" : { "description" : "A card object containing the details of the card to be use for the transaction. May be used to trigger the storage of these details by populating the `tokenisation` field.", "oneOf" : [ { "$ref" : "#/components/schemas/Card" } ] }, "token" : { "description" : "A `token` reference object, referencing a previously created `token`", "oneOf" : [ { "$ref" : "#/components/schemas/TokenReference" } ] }, "transaction" : { "description" : "A `transaction` reference, referencing a `transaction` that has completed processing. This source is required for `capture` and `void` `Transactions`, and may be used for `refund` `transactions`", "oneOf" : [ { "$ref" : "#/components/schemas/TransactionReference" } ] }, "session" : { "description" : "A `payment session` reference. A payment session may be used when implementing Hosted Payment Fields onto an Ecom site.", "oneOf" : [ { "$ref" : "#/components/schemas/SessionReference" } ] }, "googlePay" : { "description" : "An object representing a Google Pay transaction source. Either contains the encrypted payment token provided by the Google Pay web/android system (if the transaction has not been processed) or an object detailing the underlying payment card details (if the transaction has been processed).", "oneOf" : [ { "$ref" : "#/components/schemas/GooglePayInput" }, { "$ref" : "#/components/schemas/GooglePayOutput" } ] }, "applePay" : { "description" : "An object representing an Apple Pay transaction source. Either contains the encrypted payment token container provided by the Apple Pay iOS system (if the transaction has not been processed) or an object detailing the underlying payment card details (if the transaction has been processed).", "oneOf" : [ { "$ref" : "#/components/schemas/ApplePayInput" }, { "$ref" : "#/components/schemas/ApplePayOutput" } ] }, "musqetBtc" : { "description" : "An object representing an Musqet Bitcoin transaction source.", "oneOf" : [ { "$ref" : "#/components/schemas/MusqetBtcInput" }, { "$ref" : "#/components/schemas/MusqetBtcOutput" } ] }, "networkToken" : { "description" : "An object representing an Network Token transaction source.", "oneOf" : [ { "$ref" : "#/components/schemas/NetworkTokenInput" }, { "$ref" : "#/components/schemas/NetworkTokenOutput" } ] } } }, "InitiatorInput" : { "type" : "object", "description" : "The transaction request initiator supplied by the API user. Only the description is accepted in the request; the Gateway records the initiator type as `api`.", "required" : [ "object", "description" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be `initiator`.", "enum" : [ "initiator" ], "example" : "initiator" }, "description" : { "type" : "string", "description" : "A free-text identifier or human-readable description for the API caller or application initiating the transaction. This may contain an internal service identifier such as `ecom_shop` or `my_web_app`.", "example" : "my_web_app" } } }, "Recurring" : { "type" : "object", "description" : "An object that contains information about recurring payments of a transaction request", "properties" : { "object" : { "type" : "string", "description" : "The object type. Will only be \"recurring\"", "example" : "recurring" }, "agreement" : { "type" : "string", "enum" : [ "card_on_file", "recurring", "instalment", "unscheduled" ], "description" : "The agreement type. This determines what kind of recurring payment agreement is in place." }, "initiator" : { "type" : "string", "enum" : [ "customer", "merchant" ], "description" : "The initiator. This determines who initiated the recurring payment." }, "planId" : { "type" : "string", "readOnly" : true, "description" : "The ID of the recurring payment plan." } } }, "TransactionRequest" : { "description" : "A request that initiates a transaction. A transaction request contains all of the information necessary to perform the transaction.", "type" : "object", "required" : [ "object", "action" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"transaction.request\".", "example" : "transaction.request" }, "id" : { "type" : "string", "format" : "uuid", "readOnly" : true, "description" : "Order ID. A Version 4 UUID generated at the time of creation.", "example" : "4b502950-8801-4112-ba15-88f8eb280525" }, "creationDate" : { "type" : "string", "format" : "RFC3339", "readOnly" : true, "example" : "2019-07-01T00:00:00Z", "description" : "The creation date and time of this Transaction Request" }, "ref" : { "type" : "string", "description" : "A reference supplied by the API user to identify the resulting _Transaction_. The reference may be used to search for this _Transaction_. The reference is not required to be unique.", "example" : "trans-1234" }, "action" : { "type" : "string", "enum" : [ "authorise", "capture", "pay", "refund", "void", "verify" ], "description" : "The case insensitive action that this transaction should perform. One of:\n\n* authorise -\n Performs an authorisation for the proposed transaction. A successful response from the acquirer indicates that the payment source provided is valid and that the funds are available, however no funds are transferred at this time. The acquirer may reserve the funds for a period of time. An authorisation can be captured at a later time.\n\n* capture -\n Performs a capture of a previous authorisation. A successful response from the acquirer indicates that the funds will be moved from the payer's account to the merchant's account. When performing a capture, you must provide a previously successful _Authorisation_ as the _source_, as well as the same _Order_ used for the previous _authorisation_ action.\n\n* pay -\n Performs an authorisation and capture in a single transaction. A successful response from the acquirer indicates that the payment source provided is valid, the funds are available, and that the funds will be moved from the payer's account to the merchant's account.\n\n* refund -\n Performs a refund of funds from the merchant's account to the payer's account. A successful response from the acquirer indicates that the funds will be moved from the merchant's account to the payer's account. When performing a refund, the _source_ may be a _Card_, _Token_, or a previously successful _Transaction_, depending on the underlying gateway provider.\n\n* void -\n Performs a void of a previous transaction, which will attempt to cancel the previous transaction. Whether a void will be successful depends on a number of factors, such as the amount of time between the initial transaction and the void attempt, the underlying acquirer, the transaction source, etc. In may be necessary to perform a _refund_ if the _void_ was not successful.\n\n* verify -\n Performs a verification of the _source_. The verification method used is that which is supported by the underlying payment gateway and acquirer.\n", "example" : "pay" }, "order" : { "description" : "The order this transaction request relates to. Can be either a new order created by populating the user object, or a reference object referencing a previously created order.", "oneOf" : [ { "$ref" : "#/components/schemas/ReferenceOrder" }, { "$ref" : "#/components/schemas/OrderRequest" } ] }, "currency" : { "type" : "string", "format" : "ISO4217", "description" : "The currency of the transaction, in ISO 4217 format. This is required any time an `amount` is required.", "example" : "GBP" }, "amount" : { "type" : "number", "multipleOf" : 0.01, "minimum" : 0, "description" : "The amount of this transaction. An amount is required if the action is any of the following:\n* authorise\n* capture\n* pay\n* refund\n\nHowever, if a transaction is performed that references a previous _Transaction_ as the _source_, then the _amount_ will be inherited from the referenced _Transaction_. This is appropriate for the following actions:\n* capture\n* refund\n\nNo amount is required for a **void** or **verify** action. The _currency_ field must be present any time an amount is.\n", "example" : 10 }, "threeDSecure" : { "type" : "boolean", "description" : "If the transaction should use 3D Secure if the payment source is 3D Secure enabled. Will only be used if the `platformType` is 'ecom'. Defaults to false.", "example" : true, "default" : false }, "platformType" : { "type" : "string", "enum" : [ "ecom", "moto" ], "description" : "What platform is the transaction being performed from. ECOM transactions may trigger a 3D Secure `challenge` if the source's underlying card is enrolled in the scheme. MOTO transactions will not use 3D Secure." }, "source" : { "description" : "The single source of payment for the transaction.\n* NOTE - if `source` is not populated the `sources` must be.", "oneOf" : [ { "$ref" : "#/components/schemas/Source" } ] }, "sources" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Source" }, "description" : "The sources of payment for the transaction. For example, when a Tokenisation is being used as the source, this can be supplemented with a Session containing the security code.\n* NOTE - if `source` is not populated the `sources` must be." }, "billingCustomer" : { "description" : "The billing customer information. Can be a reference to the an existing customer, or can be new customer that will be created before running the transaction.", "oneOf" : [ { "$ref" : "#/components/schemas/ReferenceCustomer" }, { "$ref" : "#/components/schemas/Customer" } ] }, "initiator" : { "$ref" : "#/components/schemas/InitiatorInput", "example" : { "object" : "initiator", "description" : "my_web_app" } }, "merchantAccountId" : { "type" : "number", "writeOnly" : true, "example" : "123456", "description" : "The merchant account to be used, bypassing merchant account selection processes." }, "attributes" : { "type" : "object", "description" : "Contains custom keys and values provided by the API user for this transaction. Upon creation these attributes will be attached to the _Transaction_ object, and not the Transaction Request object. Values can accept strings, arrays and nested objects.", "writeOnly" : true, "example" : { "transactionSource" : "Website", "transactionNotes" : { "internalRef" : "INT-1234" } } }, "links" : { "type" : "object", "readOnly" : true, "description" : "The links associated with this transaction request.", "example" : { "self" : "./transactions/96d7d98a-46fd-4d3b-a15b-b03c116ae949/request", "transaction" : "./transactions/96d7d98a-46fd-4d3b-a15b-b03c116ae949" } }, "recurring" : { "$ref" : "#/components/schemas/Recurring" } } }, "Result" : { "description" : "A Result object, containing the information sent back after a transaction has been attempted.", "type" : "object", "readOnly" : true, "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"result\".", "readOnly" : true, "example" : "result" }, "resultType" : { "type" : "string", "enum" : [ "accepted", "declined", "error" ], "readOnly" : true, "example" : "accepted", "description" : "The type of result that has been returned. One of:-\n\n\n* `accepted` -\n Transaction has been accepted.\n\n\n* `declined` -\n Transaction has been declined. More information will be present in the `resultCode` and `message` fields.\n\n\n* `error` -\n There has been an error while processing the transaction. More information will be present in\n the `resultCode` and `message` fields.\n" }, "resultCode" : { "type" : "string", "enum" : [ "approved", "invalid_merchant_account", "invalid_card_number", "invalid_expiry_date", "invalid_security_code", "requires_cardholder_name", "insufficient_billing_address", "invalid_email", "invalid_phone", "invalid_amount", "invalid_currency", "invalid_source_transaction", "requires_source_transaction", "excessively_captured", "excessively_refunded", "cannot_refund", "cannot_void", "unsupported_currency", "expired_card", "requires_security_code", "already_settled", "already_voided", "invalid_3ds", "requires_3ds", "unsupported_recurrence", "expired_source_transaction", "invalid_request", "voided_source_transaction", "declined", "declined_insufficient_funds", "referred_retain_card", "blocked_blacklisted", "excessively_authed", "excessively_declined", "cancelled_continuous_authority", "incorrect_security_code", "incorrect_expiry_date", "blocked_fraud", "referred", "error_comms", "error_system", "error_unknown", "timeout", "no_response" ], "readOnly" : true, "example" : "approved", "description" : "A self descriptive result code. There may be additional information in the `message` field if needed." }, "message" : { "type" : "string", "readOnly" : true, "description" : "A field containing additional information on the result received if required." } } }, "Auth" : { "description" : "An object containing the payment Auth data if a successful transaction has been made.", "type" : "object", "readOnly" : true, "properties" : { "object" : { "type" : "string", "description" : "The object type. Will be \"auth\".", "readOnly" : true, "example" : "auth" }, "code" : { "type" : "string", "readOnly" : true, "description" : "The auth code received from the underlying acquirer upon successful transaction." }, "date" : { "type" : "string", "format" : "RFC3339", "description" : "The time that this transaction authed.", "readOnly" : true, "example" : "2019-07-01T00:00:00Z" } } }, "TransactionResponse" : { "description" : "A Transaction Response object, containing the payment result and auth data.", "type" : "object", "readOnly" : true, "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"transaction.response\".", "readOnly" : true, "example" : "transaction.response" }, "id" : { "type" : "string", "format" : "uuid", "readOnly" : true, "description" : "The transaction response ID." }, "result" : { "$ref" : "#/components/schemas/Result" }, "auth" : { "$ref" : "#/components/schemas/Auth" }, "token" : { "$ref" : "#/components/schemas/Token" } } }, "ChallengeThreeDSecureV1" : { "description" : "An object containing the information required to initiate the 3D Secure version 1 flow.", "type" : "object", "properties" : { "object" : { "type" : "string", "readOnly" : true, "description" : "The object type. Must be \"transaction.challenge.threeDSecure.v1\"", "example" : "transaction.challenge.response.threeDSecure.v1" }, "acsUrl" : { "type" : "string", "readOnly" : true, "description" : "The card issuer's access control server URL.", "example" : "https://acs.issuer.example.com/3ds/" }, "paReq" : { "type" : "string", "readOnly" : true, "description" : "Payer Authentication Request message. Contains Base64 encoded information to be passed on in the 3D Secure request.", "example" : "eJxVUslOw...lG2iWuLM=" }, "md" : { "type" : "string", "readOnly" : true, "description" : "Merchant Data. Posted back to your TermUrl once the 3D Secure process has finished.", "example" : "dGVzdCBkYXRh" } } }, "ChallengeThreeDSecureV2" : { "description" : "An object containing the information required to initiate a 3D Secure version 2 authentication.", "type" : "object", "properties" : { "object" : { "type" : "string", "readOnly" : true, "description" : "The object type. will be \"transaction.challenge.threeDSecure.v2\"", "example" : "transaction.challenge.threeDSecure.v2" }, "acsUrl" : { "type" : "string", "readOnly" : true, "description" : "The card issuer's access control server URL.", "example" : "https://acs.issuer.example.com/3ds/" } } }, "ChallengeThreeDSecure" : { "description" : "An object containing the information required to resolve a challenge caused by a 3D Secure requirement.", "type" : "object", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "readOnly" : true, "description" : "The object type. Will be \"transaction.challenge.threeDSecure\"", "example" : "transaction.challenge.threeDSecure" }, "v1" : { "$ref" : "#/components/schemas/ChallengeThreeDSecureV1" }, "v2" : { "$ref" : "#/components/schemas/ChallengeThreeDSecureV2" } } }, "Challenge" : { "description" : "An object containing the information required to resolve a challenged transaction.", "type" : "object", "required" : [ "object", "threeDSecure" ], "properties" : { "object" : { "type" : "string", "readOnly" : true, "description" : "The object type. Will be \"transaction.challenge\"", "example" : "transaction.challenge" }, "id" : { "type" : "string", "readOnly" : true, "description" : "The Challenge Id", "example" : "c6202950-8801-4112-ba15-88f8eb280907" }, "threeDSecure" : { "$ref" : "#/components/schemas/ChallengeThreeDSecure" } } }, "Transaction" : { "description" : "A Transaction object. Contains details about a Transaction's status. A Transaction cannot be created directly, instead, a TransactionRequest object must be POSTed to the transactions endpoint.", "type" : "object", "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"transaction\".", "readOnly" : true, "example" : "transaction" }, "id" : { "type" : "string", "format" : "uuid", "description" : "A unique ID for this transaction. A version 4 UUID generated at time of creation.", "readOnly" : true, "example" : "4b502950-8801-4112-ba15-88f8eb280525" }, "creationDate" : { "type" : "string", "format" : "RFC3339", "description" : "The date that this transaction was created (rfc3339 format). This will be identical to the date held within the transaction request.", "readOnly" : true, "example" : "2019-07-01T00:00:00Z" }, "status" : { "type" : "string", "enum" : [ "processing", "challenged", "processed" ], "readOnly" : true, "description" : "The current status of the transaction. These will be one of:\n* **processing** - The transaction is currently being processed. To wait for the result, a GET request can\nbe made to the transaction's endpoint with a polltime. If the status changes before the polltime expires,\nthe transaction will be returned.\n* **challenged** - The transaction has been challenged. The API user must answer the challenge before\nany further processing can be performed. A _challenge_ field will be available in the transaction object.\n* **processed** - The transaction has completed processing. A _response_ object will be available in the transaction object.\n", "example" : "processed" }, "voided" : { "type" : "boolean", "readOnly" : true, "description" : "Will be true if this transaction has been voided.\n" }, "captured" : { "type" : "boolean", "readOnly" : true, "description" : "Will be true if this transaction has been captured, in part or full.\n" }, "captured_amount" : { "type" : "number", "readOnly" : true, "multipleOf" : 0.01, "description" : "The amount that has been captured against this transaction.\n" }, "refunded" : { "type" : "boolean", "readOnly" : true, "description" : "Will be true if this transaction has been refunded, in part or full.\n" }, "refunded_amount" : { "type" : "number", "readOnly" : true, "multipleOf" : 0.01, "description" : "The amount that has been refunded against this transaction.\n" }, "request" : { "$ref" : "#/components/schemas/TransactionRequest" }, "response" : { "$ref" : "#/components/schemas/TransactionResponse" }, "challenge" : { "$ref" : "#/components/schemas/Challenge" }, "challenges" : { "type" : "array", "description" : "The challenges that have been returned against this transaction. Ordered by newest to oldest.", "items" : { "$ref" : "#/components/schemas/Challenge" } }, "attributes" : { "type" : "object", "description" : "Contains custom keys and values provided by the API user for this transaction. Can accept Strings, arrays and nested objects.", "readOnly" : true, "additionalProperties" : true, "example" : { "transactionSource" : "Website", "transactionNotes" : { "internalRef" : "INT-1234" } } }, "links" : { "type" : "object", "description" : "Links for this object", "readOnly" : true, "properties" : { "self" : { "type" : "string", "description" : "A link to this object", "example" : "./transactions/4b502950-8801-4112-ba15-88f8eb280525" } }, "example" : { "self" : ".h/transactions/4b502950-8801-4112-ba15-88f8eb280525" } } } }, "ChallengeResponseThreeDSecureV1" : { "description" : "An object containing the results of a 3D Secure version 1 authentication.", "type" : "object", "required" : [ "object", "paRes", "md" ], "properties" : { "object" : { "type" : "string", "description" : "the object type. Must be \"transaction.challenge.response.threeDSecure.v1\"", "example" : "transaction.challenge.response.threeDSecure.v1" }, "paRes" : { "type" : "string", "description" : "The pa response field received from the 3D Secure provider once the customer's authentication has been completed.", "example" : "0207e0b7-667e-4fd1-b23c-e57645f72fce" }, "md" : { "type" : "string" } } }, "ChallengeResponseThreeDSecureV2" : { "description" : "An object containing the results of a 3D Secure version 2 authentication.", "type" : "object", "required" : [ "object", "dsTransId", "eci", "transStatus" ], "properties" : { "object" : { "type" : "string", "description" : "the object type. Must be \"transaction.challenge.response.threeDSecure.v2\"", "example" : "transaction.challenge.response.threeDSecure.v2" }, "dsTransId" : { "type" : "string", "description" : "The `dsTransId` field received from the 3D Secure provider once the customer's authentication has been completed.", "example" : "0207e0b7-667e-4fd1-b23c-e57645f72fce" }, "authenticationValue" : { "type" : "string", "description" : "The authentication value received from the 3D Secure provider once the customer's authentication has been completed. May be null or empty if the authentication was unsuccessful.", "example" : "jtx5y73uj901bqtjz54qm92rpbj=" }, "eci" : { "type" : "string", "description" : "The eci value received from the 3D Secure provider once the customer's authentication has been completed. Normally a string comprised of 2 digits with a leading zero.", "example" : 5 }, "transStatus" : { "type" : "string", "description" : "The transaction status value received from the 3D Secure provider once the customer's authentication has been completed. Normally a single uppercase letter.", "example" : "Y" }, "threeDSVersion" : { "type" : "string", "description" : "The 3D Secure version used for the challenge.", "example" : "2.1.0" } } }, "ChallengeResponseThreeDSecure" : { "description" : "An object containing the results of a 3D Secure payment process. In addition to the marked required item(s), at least one of `v1` or `v2` is required.", "type" : "object", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "the object type. Must be \"transaction.challenge.response.threeDSecure\"", "example" : "transaction.challenge.response.threeDSecure" }, "v1" : { "$ref" : "#/components/schemas/ChallengeResponseThreeDSecureV1" }, "v2" : { "$ref" : "#/components/schemas/ChallengeResponseThreeDSecureV2" } } }, "ChallengeResponseMusqetBtc" : { "description" : "An object containing the values returned by Musqet after a Bitcoin payment challenge has completed.", "type" : "object", "required" : [ "object", "businessId", "checkoutId", "btcAmount", "status", "resultType" ], "properties" : { "object" : { "type" : "string", "description" : "the object type. Must be \"transaction.challenge.response.musqetBtc\"", "example" : "transaction.challenge.response.musqetBtc" }, "businessId" : { "type" : "string", "description" : "The Musqet Business ID returned by Musqet for the client.", "example" : "orics50o20001ri7o269blace" }, "checkoutId" : { "type" : "string", "description" : "The checkout ID returned by Musqet for the completed transaction.", "example" : "001d0fb7-ab81-43fa-8174-960cb49cc7f9" }, "btcAmount" : { "type" : "number", "multipleOf" : 1, "minimum" : 0, "description" : "The Satoshi amount returned by Musqet for the completed transaction.", "example" : 67890 }, "status" : { "type" : "string", "description" : "The transaction status returned by Musqet.", "example" : "PAID" }, "resultType" : { "type" : "string", "enum" : [ "ACCEPTED", "DECLINED", "ERROR" ], "description" : "The Services API result type to apply when resolving the challenge.", "example" : "ACCEPTED" } } }, "ChallengeResponse" : { "description" : "An object containing the results of a 3D Secure payment process.", "type" : "object", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "the object type. Must be \"transaction.challenge.response\"", "example" : "transaction.challenge.response" }, "threeDSecure" : { "$ref" : "#/components/schemas/ChallengeResponseThreeDSecure" }, "musqetBtc" : { "$ref" : "#/components/schemas/ChallengeResponseMusqetBtc" } } }, "SessionInput" : { "description" : "The object used to start a payment session. Uses a list of strings to specify the fields required.", "type" : "object", "required" : [ "object", "fields" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"session\".", "example" : "session" }, "fields" : { "type" : "array", "description" : "A list of strings, specifying which fields are to be available in the created session. Currently the supported field names are `pan`, `expiryDate` and `securityCode`", "items" : { "type" : "string", "enum" : [ "pan", "expiryDate", "securityCode" ] }, "example" : [ "pan", "expiryDate", "securityCode" ] } } }, "Session" : { "description" : "An object containing the payment session details. In order to read a field's value in a regular API request, the scope `session_limited_read` is required in when retrieving authentication.", "type" : "object", "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"session\".", "example" : "session" }, "id" : { "type" : "string", "format" : "uuid", "readOnly" : true, "description" : "The session ID. Will be an automatically generated Version 4 UUID." }, "creationDate" : { "type" : "string", "format" : "RFC3339", "readOnly" : true, "example" : "2019-07-01T00:00:00Z", "description" : "The creation date and time of this Session" }, "sessionExpiry" : { "type" : "string", "format" : "RFC3339", "readOnly" : true, "example" : "2019-07-01T00:00:00Z", "description" : "The expiry date and time of this Session" }, "lastUpdated" : { "type" : "string", "format" : "RFC3339", "readOnly" : true, "example" : "2019-07-01T00:00:00Z", "description" : "The time the session was last udpated." }, "sessionFields" : { "type" : "array", "description" : "A list of the fields and their details in this session.", "items" : [ { "type" : "object", "properties" : { "name" : { "type" : "string", "description" : "The name of the field." }, "value" : { "type" : "string", "description" : "The field value. Will be based on what type of field it is." }, "state" : { "type" : "string", "enum" : [ "unset", "updating", "valid", "invalid" ], "description" : "Describes the state the field is currently in." }, "selected" : { "type" : "boolean", "description" : "If the field is currently selected in the browser." }, "message" : { "type" : "string", "description" : "If the field is invalid, this will be a message explaining why." }, "links" : { "type" : "object", "readOnly" : true, "description" : "The links associated with this session field", "example" : { "iframeUrl" : "./hpf/v1/96d7d98a-46fd-4d3b-a15b-b03c116ae949/pan" } } } } ], "example" : [ { "name" : "pan", "value" : "4000000******0002", "state" : "valid", "selected" : false, "message" : "", "links" : { "iframeUrl" : "./hpf/v1/96d7d98a-46fd-4d3b-a15b-b03c116ae949/pan" } }, { "name" : "securityCode", "value" : "**", "state" : "invalid", "selected" : true, "message" : "", "links" : { "iframeUrl" : "./hpf/v1/96d7d98a-46fd-4d3b-a15b-b03c116ae949/securityCode" } }, { "name" : "expiryDate", "value" : "", "state" : "unset", "selected" : true, "message" : "", "links" : { "iframeUrl" : "./hpf/v1/96d7d98a-46fd-4d3b-a15b-b03c116ae949/securityCode" } } ] } } }, "SessionFieldInput" : { "description" : "An object used for updating a specific field in a session. At least one field other than `object` must be populated.", "type" : "object", "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"session\".", "example" : "sessionField" }, "state" : { "type" : "string", "enum" : [ "unset", "updating", "valid", "invalid" ], "description" : "Describes the state the field is currently in." }, "value" : { "type" : "string", "description" : "The value of the field. This will be validated based on the type the field is. Once a session object is returned after submitting the field value change, the validation result will be there." }, "selected" : { "type" : "boolean", "description" : "If the field should be marked as selected." }, "sequenceId" : { "type" : "number", "description" : "An ID that must be incremented each time an update is made to ensure the latest update is returned upon completion." } } }, "IssuerResult" : { "type" : "object", "description" : "An object that contains information of an issuer search.", "readOnly" : true, "properties" : { "object" : { "type" : "string", "description" : "The object type. Will only be \"issuer.result\"", "example" : "issuer.result", "readOnly" : true }, "issuer" : { "type" : "object", "description" : "An object that contains information about the issuer of a card. This will be available for cards used as a source of funds and tokens used, at retrieval.", "readOnly" : true, "properties" : { "object" : { "type" : "string", "description" : "The object type. Will only be \"issuer\"", "example" : "issuer", "readOnly" : true }, "scheme" : { "type" : "string", "description" : "The card scheme", "example" : "Visa", "readOnly" : true }, "type" : { "type" : "string", "description" : "The card type", "example" : "Credit", "readOnly" : true }, "level" : { "type" : "string", "description" : "The card level", "example" : "Classic", "readOnly" : true }, "brand" : { "type" : "string", "description" : "The issuer brand", "example" : "Barclays Bank Plc", "readOnly" : true }, "country" : { "type" : "string", "description" : "The issuer country (Alpha-2 Code)", "example" : "GB", "readOnly" : true } } }, "accepted" : { "type" : "boolean", "description" : "Whether the resulting issuer's card is accepted as a payment source.", "example" : true, "readOnly" : true }, "infringements" : { "type" : "array", "description" : "The infringing factors causing payment cards from this issuer to be invalid.", "items" : { "type" : "string", "enum" : [ "scheme", "brand", "type", "level", "common level", "country", "web address", "telephone number" ] } } } }, "ApplePayCertificateSigningRequestRequest" : { "description" : "An object representing the request to generate an Apple Pay Payment Processing public key certificate which will be used within your Apple developer account.", "type" : "object", "required" : [ "merchantIdentifier" ], "properties" : { "merchantIdentifier" : { "type" : "string", "description" : "The merchant identifier that you have registered within your Apple developer account.", "example" : "merchant.example-company.production" } } }, "ApplePayCertificateSigningRequestResponse" : { "description" : "An Apple Pay certificate signing request response object. Used to provide the CSR that is to be uploaded to Apple.", "type" : "object", "properties" : { "id" : { "type" : "string", "readOnly" : true, "description" : "The ID of the certificate that will be used as part of the request to upload the certificate that is generated by Apple.", "example" : "2ca74581-5de2-4a6c-84de-fa47ff758c16" }, "csr" : { "type" : "string", "readOnly" : true, "format" : "Privacy-Enhanced Mail", "description" : "The certificate signing request that you will need to upload to Apple using your developer account in PEM format i.e. the lines \"-----BEGIN CERTIFICATE REQUEST-----\", the certificate material encoded in Base64 and \"-----END CERTIFICATE REQUEST-----\".", "example" : "-----BEGIN CERTIFICATE REQUEST----- MIHZMIGBAgEAMB8xEDAOBgNVBAoMB0VuY29kZWQxCzAJBgNVBAYTAkdCMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/XoGBUX8cuCCRovY1bxARjp5sl9hsk6yaBG/J3rBQoI9GmDpc6k4HbQfWaUo/3mNMxbAU6v09TMUGx1c43brTaAAMAoGCCqGSM49BAMCA0cAMEQCIEI6RssKkutVbmIdfwAXQj8c+087uV+cNf2AHJcgcLS1AiB682f8sWjhDc5G11kKGh/FHTEXkAYKULW60b6BDliOmg== -----BEGIN CERTIFICATE REQUEST-----" }, "links" : { "type" : "object", "readOnly" : true, "description" : "The links associated with this certificate signing request generation.", "example" : { "uploadCertificate" : "./applepay/certificates/2ca74581-5de2-4a6c-84de-fa47ff758c16" } } } }, "ApplePayPublicKeyCertificateRequest" : { "description" : "An object representing the Apple Pay Payment Processing public key certificate that is to be uploaded in order to decrypt token and use them for transactions.", "type" : "object", "required" : [ "certificate" ], "properties" : { "certificate" : { "type" : "string", "format" : "Privacy-Enhanced Mail", "description" : "The public key certificate that was generated by Apple in PEM format i.e. the lines \"-----BEGIN CERTIFICATE-----\", the certificate material encoded in Base64 and \"-----END CERTIFICATE-----\".", "example" : "'-----BEGIN CERTIFICATE----- MIHZMIGBAgEAMB8xEDAOBgNVBAoMB0VuY29kZWQxCzAJBgNVBAYTAkdCMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/XoGBUX8cuCCRovY1bxARjp5sl9hsk6yaBG/J3rBQoI9GmDpc6k4HbQfWaUo/3mNMxbAU6v09TMUGx1c43brTaAAMAoGCCqGSM49BAMCA0cAMEQCIEI6RssKkutVbmIdfwAXQj8c+087uV+cNf2AHJcgcLS1AiB682f8sWjhDc5G11kKGh/FHTEXkAYKULW60b6BDliOmg== -----BEGIN CERTIFICATE-----'" } } }, "PlanOrder" : { "description" : "A reference to an Order object for the payment plan, only containing the ID", "type" : "object", "required" : [ "object", "string" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"order\".", "example" : "order" }, "id" : { "type" : "string", "format" : "uuid", "description" : "Order ID. A Version 4 UUID generated at the time of creation.", "example" : "123e4567-e89b-12d3-a456-426614174000" } } }, "Retries" : { "type" : "object", "description" : "An object that contains information about the retries for a payment plan", "properties" : { "amount" : { "type" : "integer", "description" : "The amount of retries", "example" : 3 }, "duration" : { "type" : "string", "description" : "The duration between retries", "example" : "PT1H" } } }, "DailySchedule" : { "type" : "object", "description" : "An object that contains information about the daily schedule for a payment plan", "required" : [ "time" ], "properties" : { "interval" : { "type" : "integer", "description" : "The number of days between each payment", "example" : 1 }, "time" : { "type" : "string", "format" : "time", "description" : "The time the payment is processed at (HH:mm:ss, no timezone)", "example" : "12:00:00" }, "timezone" : { "type" : "string", "format" : "tz", "description" : "The timezone for when the payment is processed, expressed as an IANA time zone ID", "example" : "Europe/London" } } }, "WeeklySchedule" : { "type" : "object", "description" : "An object that contains information about the daily schedule for a payment plan", "required" : [ "day", "interval", "time" ], "properties" : { "day" : { "type" : "integer", "description" : "The day of the week the payment is processed at", "example" : 4 }, "interval" : { "type" : "integer", "description" : "The number of weeks between each payment", "example" : 2 }, "time" : { "type" : "string", "format" : "time", "description" : "The time the payment is processed at (HH:mm:ss, no timezone)", "example" : "12:00:00" }, "timezone" : { "type" : "string", "format" : "tz", "description" : "The timezone for when the payment is processed, expressed as an IANA time zone ID", "example" : "Europe/London" } } }, "MonthlySchedule" : { "type" : "object", "description" : "An object that contains information about the monthly schedule for a payment plan", "required" : [ "day", "interval", "time" ], "properties" : { "day" : { "type" : "integer", "description" : "The day of the month the payment is processed at", "example" : 20 }, "interval" : { "type" : "integer", "description" : "The number of months between each payment", "example" : 1 }, "time" : { "type" : "string", "format" : "time", "description" : "The time the payment is processed at (HH:mm:ss, no timezone)", "example" : "12:00:00" }, "timezone" : { "type" : "string", "format" : "tz", "description" : "The timezone for when the payment is processed, expressed as an IANA time zone ID", "example" : "Europe/London" } } }, "YearlySchedule" : { "type" : "object", "description" : "An object that contains information about the yearly schedule for a payment plan", "required" : [ "day", "interval", "time" ], "properties" : { "day" : { "type" : "integer", "description" : "The day of the month the payment is processed at", "example" : 20 }, "month" : { "type" : "integer", "description" : "The month of the year the payment is processed at", "example" : 8 }, "interval" : { "type" : "integer", "description" : "The number of years between each payment", "example" : 1 }, "time" : { "type" : "string", "format" : "time", "description" : "The time the payment is processed at (HH:mm:ss, no timezone)", "example" : "12:00:00" }, "timezone" : { "type" : "string", "format" : "tz", "description" : "The timezone for when the payment is processed, expressed as an IANA time zone ID", "example" : "Europe/London" } } }, "Schedule" : { "type" : "object", "description" : "An object that contains information about the schedule for a payment plan", "properties" : { "daily" : { "$ref" : "#/components/schemas/DailySchedule" }, "weekly" : { "$ref" : "#/components/schemas/WeeklySchedule" }, "monthly" : { "$ref" : "#/components/schemas/MonthlySchedule" }, "yearly" : { "$ref" : "#/components/schemas/YearlySchedule" } } }, "PlanToken" : { "description" : "A reference to a Source object for the payment plan. It must contain a token with only the ID.", "type" : "object", "required" : [ "object", "id" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"token\".", "example" : "token" }, "id" : { "type" : "string", "format" : "uuid", "description" : "The token ID", "example" : "0983e003-d84d-45d6-b1dd-ceaf7e017bc1" } } }, "PlanSource" : { "description" : "A reference to a Source object for the payment plan. It must contain a token with only the ID.", "type" : "object", "required" : [ "object", "token" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"source\".", "example" : "source" }, "token" : { "$ref" : "#/components/schemas/PlanToken" } } }, "PlanTransaction" : { "description" : "A reference to a Transaction object for the payment plan", "type" : "object", "required" : [ "object", "source" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Must be \"transaction\".", "example" : "transaction" }, "source" : { "$ref" : "#/components/schemas/PlanSource" } } }, "PaymentPlanCreate" : { "type" : "object", "description" : "An object that contains information about a payment plan", "properties" : { "ref" : { "type" : "string", "description" : "A reference supplied by the API user to identify this payment plan" }, "type" : { "type" : "string", "enum" : [ "subscription", "installment" ], "description" : "The type of planned payment" }, "order" : { "$ref" : "#/components/schemas/PlanOrder", "description" : "A reference to an Order object for the payment plan, only containing the ID" }, "retries" : { "$ref" : "#/components/schemas/Retries" }, "schedule" : { "$ref" : "#/components/schemas/Schedule" }, "creationDate" : { "type" : "string", "format" : "RFC3339", "readOnly" : true, "example" : "2019-07-01T00:00:00Z", "description" : "The creation date and time of payment plan." }, "startDate" : { "type" : "string", "format" : "yyyy-MM-dd", "description" : "The start date of the payment plan", "example" : "2025-01-01" }, "endDate" : { "type" : "string", "format" : "yyyy-MM-dd", "description" : "The end date of the payment plan", "example" : "2025-12-12" }, "transaction" : { "$ref" : "#/components/schemas/PlanTransaction" } } }, "PaymentPlan" : { "type" : "object", "description" : "An object that contains information about a payment plan", "properties" : { "id" : { "type" : "string", "format" : "uuid", "readOnly" : true, "description" : "ID of the payment plan" }, "ref" : { "type" : "string", "description" : "A reference supplied by the API user to identify this payment plan" }, "type" : { "type" : "string", "enum" : [ "subscription", "installment" ], "description" : "The type of planned payment" }, "customer" : { "readOnly" : true, "allOf" : [ { "$ref" : "#/components/schemas/Customer" } ] }, "order" : { "$ref" : "#/components/schemas/PlanOrder", "description" : "A reference to an Order object for the payment plan, only containing the ID" }, "retries" : { "$ref" : "#/components/schemas/Retries" }, "schedule" : { "$ref" : "#/components/schemas/Schedule" }, "creationDate" : { "type" : "string", "format" : "RFC3339", "readOnly" : true, "example" : "2019-07-01T00:00:00Z", "description" : "The creation date and time of payment plan." }, "startDate" : { "type" : "string", "format" : "yyyy-MM-dd", "description" : "The start date of the payment plan", "example" : "2025-01-01" }, "endDate" : { "type" : "string", "format" : "yyyy-MM-dd", "description" : "The end date of the payment plan", "example" : "2025-12-12" }, "transaction" : { "$ref" : "#/components/schemas/PlanTransaction" }, "status" : { "type" : "string", "enum" : [ "init", "active", "inactive", "deleted" ], "description" : "The status of the payment plan" }, "links" : { "type" : "object", "readOnly" : true, "description" : "The links associated with this payment plan.", "example" : { "scheduledPayments" : "https://prod.encoded.services/api/v1/plans/{plan_id}/payments?status=pending", "payments" : "https://prod.encoded.services/api/v1/plans/{plan_id}/payments?status=completed&status=failed&status=canceled" } } } }, "PaymentPlanUpdate" : { "type" : "object", "description" : "An object that contains information about a payment plan", "properties" : { "order" : { "$ref" : "#/components/schemas/PlanOrder", "description" : "A reference to an Order object for the payment plan, only containing the ID" }, "retries" : { "$ref" : "#/components/schemas/Retries" }, "endDate" : { "type" : "string", "format" : "yyyy-MM-dd", "description" : "The end date of the payment plan", "example" : "2025-12-12" }, "transaction" : { "$ref" : "#/components/schemas/PlanTransaction" }, "status" : { "type" : "string", "enum" : [ "init", "active", "inactive", "deleted" ], "description" : "The status of the payment plan" } } }, "PaymentPlanPayment" : { "type" : "object", "description" : "An object that contains information about a payment within a payment plan", "properties" : { "id" : { "type" : "string", "format" : "uuid", "readOnly" : true, "description" : "ID of the payment" }, "status" : { "type" : "string", "readOnly" : true, "enum" : [ "completed", "pending", "failed", "cancelled", "paused" ], "description" : "The status of the payment" }, "plannedDate" : { "type" : "string", "format" : "RFC3339", "description" : "The planned date of this payment in RFC3339 format.", "readOnly" : true, "example" : "2025-06-15T00:00:00Z" }, "attemptDate" : { "type" : "string", "format" : "RFC3339", "description" : "The date this transaction will be attempted in RFC3339 format. If the payment has already concluded, this will be the date of the last attempt.", "readOnly" : true, "example" : "2025-06-15T00:00:00Z" }, "order" : { "$ref" : "#/components/schemas/OrderResponse", "description" : "The order associated with this payment" }, "transactions" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Transaction" }, "description" : "A list of transactions performed for this planned payment" } } }, "Initiator" : { "type" : "object", "description" : "An object that contains information about the initiator of a transaction request", "readOnly" : true, "required" : [ "object" ], "properties" : { "object" : { "type" : "string", "description" : "The object type. Will only be \"initiator\"", "enum" : [ "initiator" ], "example" : "initiator" }, "type" : { "type" : "string", "enum" : [ "api", "hpp", "service" ], "description" : "The initiator type. This is provided in the response, but does not need to be provided as part of the request. Any request from the API will have \"api\" as the type, and any request from the hosted payment page will have \"hpp\" as the type.", "readOnly" : true }, "description" : { "type" : "string", "description" : "The initiator description. This is a free text field that allows the initiator to provide an identifier or human-readable description to provide additional information about the initiator of the transaction. This may, for example, contain a identifier to an internal service run by the initiator, such as \"ecom_shop\", or \"my_web_app\".", "example" : "my_web_app" } } }, "HostedPaymentPageConfigInputMusqetBitcoin" : { "$ref" : "#/components/schemas/HostedPaymentPageConfigInputMusqetBtc" }, "HppViewPaymentMusqetBtc" : { "$ref" : "#/components/schemas/HppViewPaymentMusqetBitcoin" } } } }