Skip to content

Instantly share code, notes, and snippets.

@ifle

ifle/PaymentsAPI.json

Last active January 27, 2021 15:21
Show Gist options
  • Save ifle/bc321899362cca303ef956d6c3523b70 to your computer and use it in GitHub Desktop.
Save ifle/bc321899362cca303ef956d6c3523b70 to your computer and use it in GitHub Desktop.
Download ZIP
Zooz PaymentsOS API
Raw
PaymentsAPI.json
{
"openapi": "3.0.0",
"servers": [
{
"url": "https://api.paymentsos.com/"
}
],
"info": {
"x-logo": {
"url": "payos_logo_blue_pad.png",
"backgroundColor": "white"
},
"description": "# Overview\n\nThe PaymentsOS API allows merchants to accept payments using a variety of methods in different currencies. The API is built on REST principles, ensuring that it is a well structured and predictable API. For ease of use, it incorporates strong HTTP features such as verbs and response codes.\n\n## Live vs. Test\n\nWe strongly recommend that you test your integration before going live. For this purpose, we provide a test environment in addition to the live environment, for testing your API requests.The test environment is completely separate from the live environment and the banking networks. It provides a safe place to develop and test your integration. It allows you to simulate all the relevant requests, and directs them either to the provider's sandbox, if they have one, or to a mock provider.\n\nSwitching between the two environments is easily done, by replacing the relevant keys, and updating the `x-payments-os-env` request header key to either `live` or `test`. The default of the `x-payments-os-env` header key is `live` if not specified, or if an unrecognized value is provided.\n\n## API Versioning\n\nThe `api-version` request header specifies the version of the API platform that should process the request. Sending this header with each API request ensures that your integration will continue to work in the way it was designed, and will not be negatively affected by future upgrades that could potentially break it. Read our [changelog](https://developers.paymentsos.com/docs/paymentsos-api-changelog.html) to view all the changes in our API.\n\nTo ensure that your request uses the correct API version, make sure to include the api-version header in all API requests. If the api-version header is not included in an API request, then 1.0.0 is used as the default API version.\n\n\n## Idempotency\n\nUsing the Idempotency feature is a way of preventing double charges and data corruption caused by sending duplicate requests.\n\nTo send a post request that is \"Idempotent safe\", simply include an `idempotency-key` header. The `idempotency-key` must be unique and should only be used in one request. The content of the key is completely up to you. For example, you can use some transaction related string, or generate a random string.\n\n### Re-sending a request until you get a response\n\nYou can safely re-send a request containing an `idempotency-key`, within the \"24 hour safe-retry window\", until you actually get a response from the server.\n\n### Re-sending a request after receiving certain error responses\n\nThe following error responses allow you to continue re-sending the same request. In such cases you should make sure to use the same `idempotency-key`, to avoid creating multiple resources:\n\n* Error response: 500 - Server Error\n* Error response: 503 - Service Unavailable\n* Response Category: provider_error\n* Response Category: provider_network_error\n\n## Customer Device\n\nYou can include information about the customer device when sending a Create Authorization or Create Charge request. This information can be used later to route transactions accordingly. To send this information, simply include the `x-client-ip-address` and/or the `x-client-user-agent` headers in the request.\n\n## Expanding Objects\n\nGET requests sometimes retrieve associated resource objects. For example, Payment attributes may include associated Authorization objects and Capture objects. By including the `expand` parameter in your request, you can retrieve the full set of attributes for selected associated resources. Enter a list of resources to expand, or 'all' to expand all associated resources. For example, to expand the Payment Method resource returned in a GET payments request, add the following to the end of the request, `?expand=payment_method`.\n\n## Minor Unit Currency Format\n\nAll amounts and prices must be formatted in <a href=\"https://developers.paymentsos.com/docs/minor-currency-units.html\" target=\"_blank\">Minor Units</a>.\n\n## Additional Details\n\nYou may want to include additional data in your request. For example, when charging for a taxi service, you may want to include the name of the taxi driver in the payment request. If desired, you can also use the additional data when configuring route rules that determine how your transactions are routed (for more information, see <a href=\"https://developers.paymentsos.com/docs/control-center.html#route-and-block-rules\" target=\"_blank\">Route and Block Rules</a>).\n\nTo support your custom data, some API resources include a multi-purpose `additional_details` field in key/value format. The content of this field is entirely up to you, and we will not send it to any third party.\n\n## Responses\nPaymentsOS returns standard HTTP status codes as part of the response to all API requests.\n\n <table>\n <tbody>\n <tr>\n <td><strong>200 - OK</strong></td>\n <td>The HTTP request was successful.</td>\n </tr>\n <tr>\n <td><strong>201 -&nbsp;Created</strong></td>\n <td>A new resource was created.</td>\n </tr>\n <tr>\n <td><strong>400 - Bad Request</strong></td>\n <td>The request failed due to a syntax error, or is missing a required parameter.</td>\n </tr>\n <tr>\n <td><strong>401&nbsp;-&nbsp;Unauthorized</strong></td>\n <td>No valid API key provided.</td>\n </tr>\n <tr>\n <td><strong>404 - Not Found</strong></td>\n <td>The requested resource does not exist.</td>\n </tr>\n <tr>\n <td><strong>405&nbsp;-&nbsp;Method&nbsp;Not&nbsp;Allowed</strong></td>\n <td>The request method is not supported for the requested resource.</td>\n </tr>\n <tr>\n <td><strong>409 - Conflict</strong></td>\n <td>The request conflicts with the state of the resource.</td>\n </tr>\n <tr>\n <td><strong>500 - Server Error</strong></td>\n <td>Server problem. <br><strong><em>Note</em></strong> - Re-sending the request is allowed. Use the same <code>idempotency-key</code>, to avoid creating multiple resources.</td>\n </tr>\n <tr>\n <td><strong>503&nbsp;-&nbsp;Service&nbsp;Unavailable&nbsp;</strong></td>\n <td>The provider's server is currently unavailable. <br><strong><em>Note</em></strong> - Re-sending the request is allowed. Use the same <code>idempotency-key</code>, to avoid creating multiple resources.</td>\n </tr>\n </tbody>\n </table>\n <p>&nbsp;</p>\n\n ### Errors\n\n When an API request fails (HTTP status codes in the 4xx and 5xx range), an **Error** object is returned as part of the response. No other API resources are created, retrieved or returned.\n\n <h4>The Error Object</h4>\n <table>\n <tbody>\n <tr>\n <td><strong>Attribute Name</strong></td>\n <td><strong>Description</strong></td>\n </tr>\n <tr>\n <td><strong>category</strong>\n <br><i>string</i></td>\n <td>The response category. See the response <a href=\"#response-category\">Category</a> table.</td>\n </tr>\n <tr>\n <td><strong>description</strong>\n <br><i>string</i></td>\n <td>Description of the response category.</td>\n </tr>\n <tr>\n <td><strong>more_info</strong>\n <br><i>string</i></td>\n <td>More information about the error, for example, which parameter caused the error.</td>\n </tr>\n </tbody>\n </table>\n <p>&nbsp;</p>\n\n ### Provider Results\n\n Receiving a 201 HTTP status code response does not necessarily mean that the transaction was successful. You can see the transaction status in the **Result** object, which is part of the resource that is returned.\n\n <h4>Result Object&nbsp;</h4>\n <table>\n <tbody>\n <tr>\n <td><strong>Attribute Name</strong></td>\n <td><strong>Description</strong></td>\n </tr>\n <tr>\n <td><strong>status</strong>\n <br><i>string</i></td>\n <td>The status of the result.</td>\n </tr>\n <tr>\n <td><strong>category</strong>\n <br><i>string</i></td>\n <td>The response category. See the response <a href=\"#response-category\">Category</a> table.</td>\n </tr>\n <tr>\n <td><strong>sub_category</strong>\n <br><i>string</i></td>\n <td>The response sub-category. See the response <a href=\"#response-sub-category\">Sub-category</a> table.</td>\n </tr>\n <tr>\n <td><strong>description</strong>\n <br><i>string</i></td>\n <td>Description of the response.</td>\n </tr>\n </tbody>\n </table>\n <p>&nbsp;</p>\n\n ### Response Categories\n\n The following table lists all available response categories.\n\n <h4 id=\"response-category\">Response Category</h4>\n <table>\n <tbody>\n <tr>\n <td><strong>api_authentication_error</strong></td>\n <td>We were unable to authenticate your request.</td>\n </tr>\n <tr>\n <td><strong>api_error</strong></td>\n <td>Something went wrong on our side.</td>\n </tr>\n <tr>\n <td><strong>api_request_error</strong></td>\n <td>The request is invalid. More information can be found in the <code>description</code> and <code>more_info</code> attributes of the <code>Error object</code>.</td>\n </tr>\n <tr>\n <td><strong>blocked_by_decision_engine</strong></td>\n <td>A Block Rule was applied to this transaction. You can view and modify your Block configuration in the Control Center.</td>\n </tr>\n <tr>\n <td><strong>provider_authentication_error </strong></td>\n <td>The provider is unable to authenticate the request.</td>\n </tr>\n <tr>\n <td><strong>provider_error</strong></td>\n <td>Something went wrong on the provider's side. <br><strong><em>Note</em></strong> - Re-sending the request is allowed. Use the same <code>idempotency-key</code>, to avoid creating multiple resources.</td>\n </tr>\n <tr>\n <td><strong>provider_network_error</strong></td>\n <td>Unable to reach the provider network. <br><strong><em>Note</em></strong> - Re-sending the request is allowed. Use the same <code>idempotency-key</code>, to avoid creating multiple resources.</td>\n </tr>\n <tr>\n <td><strong>provider_request_error</strong></td>\n <td>The request sent to the provider is invalid.</td>\n </tr>\n <tr>\n <td><strong>payment_method_error</strong></td>\n <td>The payment method provided is not valid. More information can be found in the <code>sub_category</code> and the <code>description</code> attributes of the <code>Result object</code>.</td>\n </tr>\n <tr>\n <td><strong>payment_method_not_supported</strong></td>\n <td>The payment method is not supported. More information can be found in the <code>description</code> and the <code>more_info</code> attributes.<br><b>Note: </b>This category only appears if the payment method is not supported. In the event of an error, refer to any of the other error categories. </td>\n </tr>\n <tr>\n <td><strong>payment_method_declined</strong></td>\n <td>Payment method declined. More information can be found in the <code>sub_category</code> and the <code>description</code> attributes of the <code>Result object</code>.</td>\n </tr>\n <tr>\n <td><strong>two_way_authentication_failed</strong></td>\n <td>Two way authentication failed. This includes SMS, redirection to external website and 3DS authentication.</td>\n </tr>\n </tbody>\n </table>\n <h4 id=\"response-sub-category\">Response Sub-category</h4>\n Sometimes a `sub_category` is included in a response, to provide extra details that are not contained in the `category`. Addtional `sub_categories `may be added from time to time.\n <table>\n <tbody>\n <tr>\n <td><strong>duplicate_request</strong></td>\n <td>This request is a duplicate of a previously sent request.</td>\n </tr>\n <tr>\n <td><strong>expired_card</strong></td>\n <td>The card has expired.</td>\n </tr>\n <tr>\n <td><strong>declined_by_issuing_bank</strong></td>\n <td>The transaction was declined by the Issuing bank.</td>\n </tr>\n <tr>\n <td><strong>declined_by_acquiring_bank</strong></td>\n <td>The transaction was declined by the Acquiring bank.</td>\n </tr>\n <tr>\n <td><strong>declined_on_fraud_check</strong></td>\n <td>The transaction was declined for fraud reasons.</td>\n </tr>\n <tr>\n <td><strong>incorrect_cardholder_data</strong></td>\n <td>The cardholder data (CVV, AVS, 3DS, Name, email) as submitted is incorrect. The cardholder should check the submitted data.</td>\n </tr>\n <tr>\n <td><strong>insufficient_funds</strong></td>\n <td>The transaction was declined due to insufficient funds.</td>\n </tr>\n <tr>\n <tr>\n <td><strong>invalid_card_number</strong></td>\n <td>The card number is not a valid credit card number.</td>\n </tr>\n <tr>\n <td><strong>invalid_card_cvv</strong></td>\n <td>The card's 'cvv' security code is invalid.</td>\n </tr>\n <tr>\n <td><strong>lost_stolen_card</strong></td>\n <td>This card was reported lost or stolen.</td>\n </tr>\n <tr>\n <td><strong>transaction_denied_by_cardholder</strong></td>\n <td>The cardholder has placed a restriction on the card, merchant or transaction.</td>\n </tr>\n <tr>\n <td><strong>transaction_not_permitted</strong></td>\n <td>Limitations apply to the use of the payment method. The cardholder should contact the card issuer.</td>\n </tr>\n <tr>\n <td><strong>transaction_requires_user_approval</strong></td>\n <td>The cardholder needs to approve the transaction.</td>\n </tr>\n </tbody>\n </table>\n <p>&nbsp;</p>\n <p><br></p>\n\n ## Zooz Request ID\n\n <p>Each API request has a unique ID, which is returned in the <code>x-zooz-request-id</code> header, of every response. You can use this ID as a reference when contacting us about a specific request.</p>\n <p><br></p>\n <p>&nbsp;</p>\n",
"version": "1.2.0",
"title": "PaymentsOS API"
},
"tags": [
{
"name": "Authorizations",
"description": "An Authorization represents a hold on funds in the customer's account. This is the first half of the two-step payment flow (the next step is known as a Capture, in which you complete the transfer to your acquiring bank)."
},
{
"name": "Captures",
"description": "Once a payment is authorized, creating a Capture completes the transfer of funds to your acquiring bank."
},
{
"name": "Charges",
"description": "A Charge is a one-step payment flow that transfers funds from the customer's account."
},
{
"name": "Credits",
"description": "Credits are payments from your account to the customer's account. They do not need to be related to any previous customer transaction."
},
{
"name": "Customers",
"description": "Use the Customers resource to store your customer data. The Customers resource provides you with access to customer data, including a customer's card information."
},
{
"name": "Payments",
"description": "A payment provides a single reference to all the transactions that make up a payment. For more information, see <a href=\"https://developers.paymentsos.com/docs/flows_operations_overview.html#understanding-the-payment-object\" target=\"_blank\">Understanding the Payment object</a> in the PaymentsOS Documentation."
},
{
"name": "Payment Methods",
"description": "A Payment Method represents a credit card associated with a customer, stored in our system with the customer's agreement (you must ask users for their consent before storing their card information). Only tokenized payment methods can be associated to customers."
},
{
"name": "Redirections",
"description": "Redirections contain URLs used to redirect your customers between your site and third-party web sites. They are typically used at checkout (for example, for 3D Secure Authentication)."
},
{
"name": "Refunds",
"description": "A refund allows you to cancel or undo a sale and return the charged amount to the customer."
},
{
"name": "Tokens",
"description": "Tokenization is a process that safeguards sensitive card data, converting a card's details to a representative token."
},
{
"name": "Voids",
"description": "A void cancels an operation (such as an authorization or capture), before it has been finalized. The most common procedure is to void an authorization."
}
],
"x-tagGroups": [
{
"name": "Reference",
"tags": [
"Tokens",
"Payments",
"Authorizations",
"Captures",
"Charges",
"Credits",
"Refunds",
"Voids",
"Customers",
"Payment Methods",
"Redirections"
]
}
],
"security": [
{
"app-id": [],
"private-key": []
}
],
"paths": {
"/payments": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
},
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
}
],
"post": {
"tags": [
"Payments"
],
"summary": "Create a Payment",
"description": "Creates a payment object, which provides a single reference to all the transactions that make up a payment. This is the first step for all financial transactions.",
"operationId": "create-a-payment",
"parameters": [
{
"$ref": "#/components/parameters/idempotency-key"
}
],
"responses": {
"201": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/payment_resource"
}
]
}
}
}
},
"400": {
"description": "Unknown request syntax.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Authentication required.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Unexpected condition - Unable to perform the request.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/new_payment"
}
}
},
"description": "Create a Payment",
"required": true
}
}
},
"/payments/{payment_id}": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
},
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/payment_id"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
}
],
"get": {
"summary": "Retrieve a Payment",
"description": "Retrieve payment details for a specific Payment.",
"tags": [
"Payments"
],
"operationId": "retrieve-a-payment",
"parameters": [
{
"$ref": "#/components/parameters/expand"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_resource"
}
}
}
},
"400": {
"description": "Unknown request syntax.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
},
"put": {
"tags": [
"Payments"
],
"summary": "Update a Payment",
"description": "Payment details can only be updated if no other action has been performed on the Payment resource. In addition to the fields that you want to update, you must re-send all the other original argument fields, because this operation replaces the Payment resource.",
"operationId": "update-a-payment",
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/payment_resource"
}
]
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"409": {
"description": "Conflict - Cannot complete the request due a status conflict.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal Error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/update_payment"
}
}
},
"description": "Payment to update",
"required": true
}
}
},
"/payments/{payment_id}/authorizations": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
},
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
}
],
"post": {
"summary": "Create an Authorization",
"description": "Create an authorization for a payment.",
"tags": [
"Authorizations"
],
"operationId": "create-an-authorization",
"parameters": [
{
"$ref": "#/components/parameters/x-client-userAgent"
},
{
"$ref": "#/components/parameters/x-client-ip-address"
},
{
"$ref": "#/components/parameters/idempotency-key"
}
],
"responses": {
"201": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/authorization_resource"
}
]
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"409": {
"description": "Conflict - Cannot complete the request due a status conflict.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal Error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"503": {
"description": "Service unavailable - The provider's server is currently unavailable.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/new_authorization"
}
}
},
"description": "Authorization of payment",
"required": true
}
},
"get": {
"summary": "Retrieve all Authorizations",
"description": "Retrieve all Authorizations for a Payment.",
"tags": [
"Authorizations"
],
"operationId": "retrieve-all-authorizations",
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/authorization_resource"
}
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal Error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/authorizations/{authorization_id}": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
},
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
}
],
"get": {
"summary": "Retrieve an Authorization",
"description": "Retrieve a specific Authorization.",
"operationId": "retrieve-an-authorization",
"parameters": [
{
"name": "authorization_id",
"in": "path",
"description": "The identifier of the authorization.",
"required": true,
"example": "3a4dc2cf-1b35-4774-80b2-e343a452985e",
"schema": {
"type": "string",
"pattern": "^[{(]?[0-9A-Fa-f]{8}[-]?([0-9A-Fa-f]{4}[-]?){3}[0-9A-Fa-f]{12}[)}]?$"
}
}
],
"tags": [
"Authorizations"
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/authorization_resource"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal Error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/captures": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"post": {
"summary": "Create a Capture",
"description": "You can capture a payment only after it is authorized. This is the second half of the two-step payment flow. For a full capture, leave the amount empty. For a partial capture, specify the capture amount. The amount is formatted in [Minor Units](https://developers.paymentsos.com/docs/minor-currency-units.html) format.",
"tags": [
"Captures"
],
"operationId": "create-a-capture",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/idempotency-key"
},
{
"$ref": "#/components/parameters/payment_id"
}
],
"responses": {
"201": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/capture_resource"
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"409": {
"description": "Conflict - Cannot capture the payment due a status conflict.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"503": {
"description": "Service unavailable - The provider's server is currently unavailable.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"reconciliation_id": {
"description": "A unique ID generated by you, used for transaction reconciliation. **Note**: This will only be sent to providers who support this.\n",
"type": "string"
},
"amount": {
"description": "The capture amount. Partial amounts can be captured, if the provider supports this (see relevant provider guides). If the first capture request that is sent does not contain `amount`, then the full authorized amount will be used as the `capture.amount`. Amount is only required for the second capture, and subsequent captures. The amount is formatted in [Minor Units](https://developers.paymentsos.com/docs/minor-currency-units.html) format.\n",
"type": "number",
"minimum": 0,
"format": "integer"
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
}
}
}
}
},
"description": "You can capture a payment, that has been authorized. For a full capture, leave the amount empty. For a partial capture, specify the capture amount. The amount is formatted in [Minor Units](https://developers.paymentsos.com/docs/minor-currency-units.html) format."
}
},
"get": {
"summary": "Retrieve all Captures",
"description": "Retrieve all Captures for a Payment",
"tags": [
"Captures"
],
"operationId": "retrieve-all-captures",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/capture_resource"
}
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/captures/{capture_id}": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"get": {
"summary": "Retrieve a Capture",
"description": "Retrieve a specific Capture.",
"tags": [
"Captures"
],
"operationId": "retrieve-a-capture",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
},
{
"name": "capture_id",
"in": "path",
"description": "The identifier of the capture.",
"required": true,
"example": "ee25e277-33a8-4081-8912-1d1363dd1ecb",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/capture_resource"
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/charges": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"post": {
"summary": "Create a Charge",
"description": "Create a new Charge.",
"tags": [
"Charges"
],
"operationId": "create-a-charge",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
},
{
"$ref": "#/components/parameters/x-client-userAgent"
},
{
"$ref": "#/components/parameters/x-client-ip-address"
},
{
"$ref": "#/components/parameters/idempotency-key"
}
],
"responses": {
"201": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/charge_resource"
}
]
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"409": {
"description": "Conflict - Cannot complete the request due a status conflict.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal Error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"503": {
"description": "Service unavailable - The provider's server is currently unavailable.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/new_charge"
}
}
},
"description": "Charge of payment",
"required": true
}
},
"get": {
"summary": "Retrieve all Charges",
"description": "Retrieve all Charges for a Payment.",
"tags": [
"Charges"
],
"operationId": "retrieve-all-charges",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/charge_resource"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal Error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/charges/{charge_id}": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"get": {
"summary": "Retrieve a Charge",
"description": "Retrieve a specific Charge.",
"operationId": "retrieve-a-charge",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
},
{
"name": "charge_id",
"in": "path",
"description": "The identifier of the charge.",
"required": true,
"example": "7bbb92be-3bea-41d3-8b01-7cb570aee811",
"schema": {
"type": "string",
"pattern": "^[{(]?[0-9A-Fa-f]{8}[-]?([0-9A-Fa-f]{4}[-]?){3}[0-9A-Fa-f]{12}[)}]?$"
}
}
],
"tags": [
"Charges"
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/charge_resource"
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal Error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/credits": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
},
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
}
],
"post": {
"summary": "Create a Credit",
"description": "Create a Credit for a payment.",
"operationId": "create-a-credit",
"tags": [
"Credits"
],
"parameters": [
{
"$ref": "#/components/parameters/x-client-userAgent"
},
{
"$ref": "#/components/parameters/x-client-ip-address"
},
{
"$ref": "#/components/parameters/idempotency-key"
}
],
"responses": {
"201": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/credit_resource"
}
]
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"409": {
"description": "Conflict - Cannot complete the request due a status conflict.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal Error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"503": {
"description": "Service unavailable - The provider's server is currently unavailable.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/new_credit"
}
}
},
"description": "Credit of payment",
"required": true
}
},
"get": {
"summary": "Retrieve all Credits",
"description": "Retrieve all Credits for a Payment.",
"operationId": "retrieve-all-credits",
"tags": [
"Credits"
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/credit_resource"
}
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal Error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/credits/{credit_id}": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
},
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
}
],
"get": {
"summary": "Retrieve a Credit",
"description": "Retrieve a specific Credit.",
"operationId": "retrieve-a-credit",
"parameters": [
{
"name": "credit_id",
"in": "path",
"description": "The identifier of the credit.",
"required": true,
"example": "3a4dc2cf-1b35-4774-80b2-e343a452985e",
"schema": {
"type": "string",
"pattern": "^[{(]?[0-9A-Fa-f]{8}[-]?([0-9A-Fa-f]{4}[-]?){3}[0-9A-Fa-f]{12}[)}]?$"
}
}
],
"tags": [
"Credits"
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/credit_resource"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal Error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/voids": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"post": {
"summary": "Create a Void",
"description": "You can void an authorized payment before it is captured. With some providers, you can also void a captured payment before the transaction is settled in your account.",
"tags": [
"Voids"
],
"operationId": "create-a-void",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/idempotency-key"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
}
],
"responses": {
"201": {
"description": "Created - Payment voided",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/void_resource"
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"409": {
"description": "Conflict - Cannot complete the request due a status conflict.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"503": {
"description": "Service unavailable - The provider's server is currently unavailable.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"additional_details": {
"$ref": "#/components/schemas/additional_details"
}
}
}
}
},
"description": "New Void"
}
},
"get": {
"summary": "Retrieve all Voids",
"description": "Retrieve all voids for a specific payment.",
"tags": [
"Voids"
],
"operationId": "retrieve-all-voids",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/void_resource"
}
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/voids/{void_id}": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"get": {
"summary": "Retrieve a Void",
"description": "Retrieve a specific Void",
"tags": [
"Voids"
],
"operationId": "retrieve-a-void",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
},
{
"name": "void_id",
"in": "path",
"description": "The identifier of the void.",
"required": true,
"example": "a6391b6d-ace7-4b14-bd2b-3686cd315626",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/void_resource"
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/refunds": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"post": {
"summary": "Create a Refund",
"description": "Refund a payment only after the payment is Charged or Captured.",
"operationId": "create-a-refund",
"tags": [
"Refunds"
],
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
},
{
"$ref": "#/components/parameters/idempotency-key"
}
],
"responses": {
"201": {
"description": "OK - Refund created",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refund_resource"
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"409": {
"description": "Conflict - Cannot refund the payment due a status conflict.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"503": {
"description": "Service unavailable - The provider's server is currently unavailable.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"reconciliation_id": {
"description": "A unique ID generated by you, used for transaction reconciliation.\n**Note**: This will only be sent to providers who support this.\n",
"type": "string"
},
"amount": {
"description": "The refund amount. Note - Partial amounts can be refunded, if the provider supports this (see relevant provider guides.) Note - If the first refund request that is sent does not contain amount, then the full captured amount will be used as the refund.amount. Note - Amount is only required for the second refund, and subsequent refunds. The amount is formatted in [Minor Units](https://developers.paymentsos.com/docs/minor-currency-units.html) format.",
"type": "integer",
"format": "integer",
"minimum": 0
},
"capture_id": {
"description": "Identifier of a Capture that is associated with this refund.",
"type": "string"
},
"refund_reason": {
"description": "The refund reason.",
"type": "string"
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
}
}
}
}
},
"description": "You can refund a payment (that has been captured). For a full refund, leave the amount empty. For a partial refund, specify the refund amount. The amount is formatted in [Minor Units](https://developers.paymentsos.com/docs/minor-currency-units.html) format."
}
},
"get": {
"summary": "Retrieve all Refunds",
"description": "Retrieve all refunds for a payment.",
"operationId": "retrieve-all-refunds",
"tags": [
"Refunds"
],
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
}
],
"responses": {
"200": {
"description": "Refunds retrieved",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/refund_resource"
}
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/refunds/{refund_id}": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"get": {
"summary": "Retrieve a Refund",
"description": "Retrieve a specific Refund.",
"operationId": "retrieve-a-refund",
"tags": [
"Refunds"
],
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
},
{
"name": "refund_id",
"in": "path",
"description": "The identifier of the refund.",
"required": true,
"example": "8ba5d459-06a4-48ca-8197-fbc71d94303e",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Refund retrieved",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refund_resource"
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/customers": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"post": {
"summary": "Create a Customer",
"description": "Create a new Customer.",
"tags": [
"Customers"
],
"operationId": "create-a-customer",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/idempotency-key"
}
],
"responses": {
"201": {
"description": "Customer created",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer_resource"
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"409": {
"description": "Conflict - Cannot complete the request due a status conflict.",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer_request"
}
}
},
"description": "Customer to create",
"required": true
}
},
"get": {
"summary": "Retrieve a Customer by Customer Reference",
"description": "Retrieve customer details by customer reference.",
"tags": [
"Customers"
],
"operationId": "retrieve-a-customer-by-customer-reference",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/customer_reference"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer_resource"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Customer not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/customers/{customer_id}": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"get": {
"summary": "Retrieve a Customer by Customer ID",
"description": "Retrieve customer details by customer ID.",
"tags": [
"Customers"
],
"operationId": "retrieve-a-customer-by-customer-id",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/customer_id"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer_resource"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Customer not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
},
"put": {
"summary": "Update a Customer",
"description": "Update Customer details. In addition to the fields that you want to update, you must re-send all the other original argument fields, because this operation replaces the Customer resource.",
"tags": [
"Customers"
],
"operationId": "update-a-customer",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/idempotency-key"
},
{
"$ref": "#/components/parameters/customer_id"
}
],
"responses": {
"200": {
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer_resource"
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Customer not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer_request"
}
}
},
"description": "Customer to update",
"required": true
}
},
"delete": {
"summary": "Delete a Customer",
"description": "This permanently deletes a customer, and cannot be undone. The customer's transaction history is not deleted.",
"tags": [
"Customers"
],
"operationId": "delete-a-customer",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/customer_id"
}
],
"responses": {
"204": {
"description": "OK - Deleted customer",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Customer not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/tokens": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"post": {
"summary": "Create a Token",
"security": [
{
"public-key": []
}
],
"description": "When creating a Token, remember to use the public-key header instead of the private-key header, and do not include the app-id header.",
"tags": [
"Tokens"
],
"operationId": "create-a-token",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/public-key"
},
{
"$ref": "#/components/parameters/idempotency-key"
}
],
"responses": {
"201": {
"description": "Token created",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/token"
},
{
"properties": {
"encrypted_cvv": {
"description": "This value can be used in a 'create authorization' or 'create charge' request, as the 'credit_card_cvv' field. The 'encrypted_cvv' field expires after three hours.",
"type": "string"
}
}
}
]
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorize",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/credit_card"
},
"example": {
"token_type": "credit_card",
"card_number": "4111111111111111",
"expiration_date": "10/29",
"holder_name": "John Mark",
"billing_address": {
"country": "USA",
"state": "NY",
"city": "NYC",
"line1": "fifth avenue 10th"
}
}
}
},
"description": "Create new token",
"required": true
}
}
},
"/tokens/{token}": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"get": {
"summary": "Retrieve a Token",
"description": "Retrieve Token details for a specific Token.",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"in": "path",
"name": "token",
"description": "The identifier of the token.",
"required": true,
"example": "f78cbf5b-0e23-44e0-be11-2081791d9501",
"schema": {
"type": "string"
}
}
],
"operationId": "retrieve-a-token",
"tags": [
"Tokens"
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/token"
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Token not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/customers/{customer_id}/payment-methods/{token}": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"post": {
"summary": "Create a Payment Method",
"description": "Associates a token with a customer.",
"tags": [
"Payment Methods"
],
"operationId": "create-a-payment-method",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/customer_id"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/idempotency-key"
},
{
"name": "token",
"in": "path",
"description": "The identifier of the token.",
"required": true,
"example": "f78cbf5b-0e23-44e0-be11-2081791d9501",
"schema": {
"type": "string"
}
}
],
"responses": {
"201": {
"description": "Payment Method created",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/tokenized_response"
}
]
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Customer not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
},
"get": {
"summary": "Retrieve a Payment Method",
"description": "Retrieve a specific Payment Method.",
"tags": [
"Payment Methods"
],
"operationId": "retrieve-a-payment-method",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/customer_id"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"in": "path",
"name": "token",
"description": "The token representing the payment method, selected by the customer to pay.",
"required": true,
"example": "f78cbf5b-0e23-44e0-be11-2081791d9501",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/tokenized_response"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment method not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
},
"delete": {
"summary": "Delete a Payment Method",
"description": "This deletes the token and removes the association between the customer resource and the token resource. You will not be able to use the token again after it has been deleted. Note that the customer's transaction history is not deleted.",
"tags": [
"Payment Methods"
],
"operationId": "delete-a-payment-method",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/idempotency-key"
},
{
"$ref": "#/components/parameters/customer_id"
},
{
"in": "path",
"name": "token",
"description": "The identifier of the token.",
"required": true,
"example": "f78cbf5b-0e23-44e0-be11-2081791d9501",
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "OK - Deleted payment method",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment method not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/customers/{customer_id}/payment-methods": {
"parameters": [
{
"$ref": "#/components/parameters/api-version"
}
],
"get": {
"summary": "Retrieve all Payment Methods",
"description": "Retrieve all payment methods for a customer.",
"tags": [
"Payment Methods"
],
"operationId": "retrieve-all-payment-methods",
"parameters": [
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"$ref": "#/components/parameters/customer_id"
},
{
"$ref": "#/components/parameters/limit"
},
{
"$ref": "#/components/parameters/offset"
},
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/tokenized_response"
}
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Customer not found",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/redirections": {
"parameters": [
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/payment_id"
},
{
"$ref": "#/components/parameters/api-version"
},
{
"$ref": "#/components/parameters/x-payments-os-env"
}
],
"get": {
"summary": "Retrieve all Redirections",
"description": "Retrieve all Redirections for a Payment.",
"tags": [
"Redirections"
],
"operationId": "retrieve-all-redirections",
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/redirection_resource"
}
}
}
}
},
"400": {
"description": "Bad request",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"401": {
"description": "Not Authorize",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment does not exist",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal Error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
},
"/payments/{payment_id}/redirections/{redirection_id}": {
"parameters": [
{
"$ref": "#/components/parameters/app-id"
},
{
"$ref": "#/components/parameters/private-key"
},
{
"$ref": "#/components/parameters/api-version"
},
{
"$ref": "#/components/parameters/payment_id"
},
{
"$ref": "#/components/parameters/x-payments-os-env"
},
{
"name": "redirection_id",
"in": "path",
"description": "The identifier of the redirection.",
"required": true,
"example": "7bbb92be-3bea-41d3-8b01-7cb570aee890",
"schema": {
"type": "string"
}
}
],
"get": {
"summary": "Retrieve a Redirection",
"description": "Retrieve a specific Redirection.",
"operationId": "retrieve-a-redirection",
"tags": [
"Redirections"
],
"responses": {
"200": {
"description": "OK",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
},
"self": {
"description": "The href link to the current resource.",
"schema": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/redirection_resource"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"404": {
"description": "Payment does not exist",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
},
"500": {
"description": "Internal Error",
"headers": {
"x-zooz-request-id": {
"description": "request id",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_model"
}
}
}
}
}
}
}
},
"components": {
"parameters": {
"private-key": {
"name": "private-key",
"in": "header",
"required": true,
"example": "0047c4ef-f658-4e6d-a040-5882e2285f34",
"schema": {
"type": "string"
}
},
"public-key": {
"name": "public-key",
"in": "header",
"required": true,
"example": "f8948bac-8f29-4a82-8cef-704fb1e6b7ca",
"schema": {
"type": "string"
}
},
"app-id": {
"name": "app-id",
"in": "header",
"required": true,
"example": "com.mycomp.mybusinessunit",
"schema": {
"type": "string"
}
},
"x-client-userAgent": {
"name": "x-client-user-agent",
"in": "header",
"description": "Identifies the client software that sent the request to you. Include this header in requests where required.",
"schema": {
"type": "string"
}
},
"x-client-ip-address": {
"name": "x-client-ip-address",
"in": "header",
"description": "The IP address of the client-userAgent (the client software that sent the request to the merchant).",
"schema": {
"type": "string",
"pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
}
},
"offset": {
"name": "offset",
"in": "query",
"description": "The number of preceding response pages to skip.",
"schema": {
"type": "integer"
}
},
"limit": {
"name": "limit",
"in": "query",
"description": "The number of objects per response page.",
"schema": {
"type": "integer"
}
},
"expand": {
"name": "expand",
"in": "query",
"description": "A list of resources to expand in the response.",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"authorizations",
"redirections",
"captures",
"refunds",
"voids",
"credits",
"customer",
"payment_method",
"all"
]
}
}
},
"payment_id": {
"name": "payment_id",
"in": "path",
"description": "The identifier of the payment.",
"required": true,
"example": "9640e09b-85d0-4509-a19c-90aa65eb386a",
"schema": {
"type": "string"
}
},
"customer_id": {
"name": "customer_id",
"in": "path",
"description": "The identifier of a customer.",
"required": true,
"example": "6f4f9afa-b3cd-44f5-a2a8-cf25f5a171fe",
"schema": {
"type": "string"
}
},
"customer_reference": {
"name": "customer_reference",
"in": "query",
"description": "The customer reference. This is the customer identifier as known in your system.",
"required": true,
"example": "6f4f9afa-b3cd-44f5-a2a8-cf25f5a171fe",
"schema": {
"type": "string"
}
},
"idempotency-key": {
"name": "idempotency-key",
"description": "Allows you to send a request that is \"idempotent safe\". The key must be unique and should only be used in one request.",
"in": "header",
"required": false,
"schema": {
"type": "string"
}
},
"x-payments-os-env": {
"name": "x-payments-os-env",
"in": "header",
"required": false,
"description": "PaymentsOS request destination environment, live or test. Default is live if not specified, or if an unrecognized value is provided.",
"example": "test",
"schema": {
"type": "string",
"enum": [
"live",
"test"
],
"default": "live"
}
},
"api-version": {
"name": "api-version",
"in": "header",
"required": false,
"description": "The version number of the PaymentsOS API. If the api-version header is not included in a request, then 1.0.0 is used.",
"schema": {
"type": "string"
}
}
},
"securitySchemes": {
"app-id": {
"type": "apiKey",
"description": "The ID that uniquely identifies the business unit accepting the payment. Grab the ID from your business unit configuration. **Note**: Create Token requests do not use the `app-id`.\n",
"in": "header",
"name": "app-id"
},
"private-key": {
"type": "apiKey",
"description": "Your private authentication key. Grab the key from your business unit configuration. **Note**: For security reasons, Create Token requests use the `public-key` instead of the `private-key`.\n",
"in": "header",
"name": "private-key"
},
"public-key": {
"type": "apiKey",
"description": "Your public authentication key. Used in Create Token requests. Grab the key from your business unit configuration.\n",
"in": "header",
"name": "public-key"
}
},
"schemas": {
"customer_resource": {
"allOf": [
{
"$ref": "#/components/schemas/customer_request"
},
{
"properties": {
"id": {
"description": "Identifier of the customer.",
"type": "string"
},
"created": {
"description": "The date and time that the customer was created.",
"type": "string",
"format": "timestamp"
},
"modified": {
"description": "The last date and time that the customer was modified.",
"type": "string",
"format": "timestamp"
},
"payment_methods": {
"description": "Payment Methods related to this customer.",
"type": "array",
"items": {
"allOf": [
{
"required": [
"href"
],
"properties": {
"href": {
"description": "The href link to the associated Payment Method.",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
{
"$ref": "#/components/schemas/tokenized_response"
}
]
}
}
}
}
]
},
"customer_request": {
"required": [
"customer_reference"
],
"properties": {
"customer_reference": {
"type": "string",
"description": "The unique customer identifier used in your system. Note - This must be unique within your PaymentsOS account."
},
"first_name": {
"type": "string",
"example": "John",
"description": "Customer's first name."
},
"last_name": {
"type": "string",
"example": "Taylor",
"description": "Customer's last name."
},
"email": {
"type": "string",
"example": "John.Taylor@gmail.com",
"description": "Customer's email address."
},
"additional_details": {
"description": "Optional additional data stored with your customer in key/value pairs.",
"example": {
"key1": "value1",
"key2": "value2"
},
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"shipping_address": {
"description": "Customer's shipping address details. Note - The shipping address in the customer resource does not over-write the shipping address that is sent in the create payment request.",
"allOf": [
{
"$ref": "#/components/schemas/address"
}
]
}
}
},
"new_payment": {
"description": "Create a new payment",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"$ref": "#/components/schemas/amount"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
},
"statement_soft_descriptor": {
"$ref": "#/components/schemas/statement_soft_descriptor"
},
"order": {
"description": "Details of the order.",
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/order_id"
},
"additional_details": {
"description": "Optional additional data stored with your order in key/value pairs.",
"additionalProperties": {
"type": "string",
"example": "The details you specify"
}
},
"line_items": {
"description": "The line items of the order.",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"description": "Name of this line item.",
"type": "string",
"example": "Garden chair"
},
"id": {
"description": "Identifier of this line item.",
"type": "string",
"example": "seg424vvkcle931686k1900old3"
},
"quantity": {
"description": "Quantity of this line item purchased.",
"type": "integer",
"example": 3
},
"unit_price": {
"description": "Unit price of the line item. The amount is formatted in <a href=\"https://developers.paymentsos.com/docs/minor-currency-units.html\" target=\"_blank\">Minor Units</a> format.",
"type": "number",
"format": "integer",
"example": 10500
}
}
}
},
"tax_amount": {
"description": "Tax amount for this order. The amount is formatted in <a href=\"https://developers.paymentsos.com/docs/minor-currency-units.html\" target=\"_blank\">Minor Units</a> format.",
"type": "integer",
"format": "integer"
},
"tax_percentage": {
"description": "Tax rate for this order.",
"type": "number",
"format": "double"
}
}
},
"customer_id": {
"type": "string",
"description": "Identifier of the customer associated with this payment.",
"example": "johntravolta18021954"
},
"shipping_address": {
"description": "Shipping address details. This will only be sent to providers who support shipping addresses, in requests that support them.\n**Note:** The shipping address details will be sent \"as is\", without any corrections or substitutions from the shipping address in the customer resource.\n",
"allOf": [
{
"$ref": "#/components/schemas/address"
}
]
},
"billing_address": {
"description": "Billing address details. This will only be sent to providers who support billing addresses, in requests that support them.\n**Note:** The billing address details will be sent \"as is\", without any corrections or substitutions from the billing address in the token resource.",
"allOf": [
{
"$ref": "#/components/schemas/address"
}
]
}
}
},
"payment_resource": {
"description": "Payment",
"required": [
"amount",
"currency",
"id",
"created",
"status"
],
"properties": {
"id": {
"description": "Identifier of the payment.",
"type": "string",
"pattern": "^[{(]?[0-9A-Fa-f]{8}[-]?([0-9A-Fa-f]{4}[-]?){3}[0-9A-Fa-f]{12}[)}]?$"
},
"created": {
"description": "The date and time that the payment was created.",
"type": "string",
"format": "timestamp"
},
"modified": {
"description": "The last date and time that the payment was modified.",
"type": "string",
"format": "timestamp"
},
"status": {
"description": "The status of the payment.",
"type": "string",
"enum": [
"Initialized",
"Credited",
"Pending",
"Authorized",
"Captured",
"Refunded",
"Voided"
]
},
"amount": {
"$ref": "#/components/schemas/amount"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
},
"statement_soft_descriptor": {
"$ref": "#/components/schemas/statement_soft_descriptor"
},
"order": {
"description": "Details of the order.",
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/order_id"
},
"additional_details": {
"description": "Optional additional data stored with your order in key/value pairs.",
"additionalProperties": {
"type": "string"
}
},
"line_items": {
"description": "The line items of the order.",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"description": "Name of this line item.",
"type": "string"
},
"id": {
"description": "Identifier of this line item.",
"type": "string"
},
"quantity": {
"description": "Quantity of this line item purchased.",
"type": "integer"
},
"unit_price": {
"description": "Unit price of the line item. The amount is formatted in [Minor Units](https://developers.paymentsos.com/docs/minor-currency-units.html) format.",
"type": "number",
"format": "integer"
}
}
}
},
"tax_amount": {
"description": "Tax amount for this order. The amount is formatted in [Minor Units](https://developers.paymentsos.com/docs/minor-currency-units.html) format.",
"allOf": [
{
"$ref": "#/components/schemas/amount"
}
]
},
"tax_percentage": {
"description": "Tax rate for this order.",
"type": "number",
"format": "double"
}
}
},
"customer": {
"description": "Customer associated with this payment.",
"allOf": [
{
"required": [
"href"
],
"properties": {
"href": {
"description": "The href link to the associated customer.",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
{
"$ref": "#/components/schemas/customer_resource"
}
]
},
"shipping_address": {
"description": "Shipping address details. This will only be sent to providers who support shipping addresses, in requests that support them.\n**Note:** The shipping address details will be sent \"as is\", without any corrections or substitutions from the shipping address in the customer resource.\n",
"allOf": [
{
"$ref": "#/components/schemas/address"
}
]
},
"billing_address": {
"description": "Billing address details. This will only be sent to providers who support billing addresses, in requests that support them.\n**Note:** The billing address details will be sent \"as is\", without any corrections or substitutions from the billing address in the token resource.",
"allOf": [
{
"$ref": "#/components/schemas/address"
}
]
},
"payment_method": {
"description": "This represents the Payment Method selected by the customer to pay.",
"allOf": [
{
"required": [
"href"
],
"properties": {
"href": {
"description": "The href link to the associated Payment Method.\nNote - The href is only included here for a payment method that is associated with a customer.\n",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
{
"$ref": "#/components/schemas/payment_method"
}
]
},
"related_resources": {
"description": "All financial transactions related to this payment.",
"type": "object",
"properties": {
"authorizations": {
"description": "Authorizations related to this payment.",
"type": "array",
"items": {
"allOf": [
{
"required": [
"href"
],
"properties": {
"href": {
"description": "The href link to the associated authorization.",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
{
"$ref": "#/components/schemas/authorization_resource"
}
]
}
},
"charges": {
"description": "Charges related to this payment.",
"type": "array",
"items": {
"allOf": [
{
"required": [
"href"
],
"properties": {
"href": {
"description": "The href link to the associated charge.",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
{
"$ref": "#/components/schemas/charge_resource"
}
]
}
},
"voids": {
"description": "Voids related to this payment.",
"type": "array",
"items": {
"allOf": [
{
"required": [
"href"
],
"properties": {
"href": {
"description": "The href link to the associated void.",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
{
"$ref": "#/components/schemas/void_resource"
}
]
}
},
"redirections": {
"description": "Redirections related to this payment.",
"type": "array",
"items": {
"allOf": [
{
"required": [
"href"
],
"properties": {
"href": {
"description": "The href link to the associated redirection.",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
{
"$ref": "#/components/schemas/redirection_resource"
}
]
}
},
"captures": {
"description": "Captures related to this payment.",
"type": "array",
"items": {
"allOf": [
{
"required": [
"href"
],
"properties": {
"href": {
"description": "The href link to the associated capture.",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
{
"$ref": "#/components/schemas/capture_resource"
}
]
}
},
"refunds": {
"description": "Refunds related to this payment.",
"type": "array",
"items": {
"allOf": [
{
"required": [
"href"
],
"properties": {
"href": {
"description": "The href link to an associated refund.",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
{
"$ref": "#/components/schemas/refund_resource"
}
]
}
}
}
},
"possible_next_actions": {
"description": "The possible next actions for the payment, according to its current status.",
"type": "array",
"items": {
"properties": {
"action": {
"type": "string",
"description": "The possible next action. Possible values - 'Authorize', 'Charge', 'Capture', 'Refund', 'Void', and 'Update Payment'.",
"enum": [
"Authorize",
"Charge",
"Capture",
"Refund",
"Void",
"Update Payment"
]
},
"href": {
"description": "The href link to the possible next action.",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
}
}
}
},
"update_payment": {
"description": "Update a payment",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"$ref": "#/components/schemas/amount"
},
"currency": {
"$ref": "#/components/schemas/currency"
},
"customer_id": {
"type": "string",
"description": "Identifier of the customer associated with this payment."
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
},
"statement_soft_descriptor": {
"$ref": "#/components/schemas/statement_soft_descriptor"
},
"order": {
"description": "Details of the order.",
"properties": {
"id": {
"description": "Identifier of the order.",
"type": "string"
},
"line_items": {
"description": "The line items of the order.",
"type": "array",
"items": {
"properties": {
"name": {
"description": "Name of this line item.",
"type": "string"
},
"id": {
"description": "Identifier of this line item.",
"type": "string"
},
"quantity": {
"description": "Quantity of this line item purchased.",
"type": "integer"
},
"unit_price": {
"description": "Unit price of the line item.",
"type": "integer",
"format": "integer"
}
}
}
},
"tax_amount": {
"description": "Tax amount for this order. The amount is formatted in [Minor Units](https://developers.paymentsos.com/docs/minor-currency-units.html) format.",
"type": "integer",
"format": "integer"
},
"tax_percentage": {
"description": "Tax rate for this order.",
"type": "number",
"format": "double"
},
"additional_details": {
"description": "Optional additional data stored with your order in key/value pairs.",
"additionalProperties": {
"type": "string"
}
}
}
},
"shipping_address": {
"description": "Shipping address details. This will only be sent to providers who\nsupport shipping addresses, in requests that support them.\n\n**Note:** The shipping address details will be sent \"as is\", without\nany corrections or substitutions from the shipping address in the\ncustomer resource.\n",
"allOf": [
{
"$ref": "#/components/schemas/address"
}
]
},
"billing_address": {
"description": "Billing address details. This will only be sent to providers who support billing addresses, in requests that support them.\n\n**Note:** The billing address details will be sent \"as is\", without\nany corrections or substitutions from the billing address in the\ntoken resource.\n",
"allOf": [
{
"$ref": "#/components/schemas/address"
}
]
}
}
},
"charge_resource": {
"description": "Charge",
"properties": {
"id": {
"description": "Identifier of the charge.",
"type": "string",
"pattern": "^[{(]?[0-9A-Fa-f]{8}[-]?([0-9A-Fa-f]{4}[-]?){3}[0-9A-Fa-f]{12}[)}]?$"
},
"result": {
"$ref": "#/components/schemas/result"
},
"amount": {
"$ref": "#/components/schemas/amount"
},
"created": {
"type": "string",
"description": "The date and time that the charge was created.",
"format": "timestamp"
},
"reconciliation_id": {
"description": "A unique ID generated by you, used for transaction reconciliation.",
"type": "string"
},
"payment_method": {
"description": "This represents the Payment Method selected by the customer to pay.",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/tokenized_response"
},
{
"$ref": "#/components/schemas/untokenized_response"
}
]
},
"three_d_secure_attributes": {
"$ref": "#/components/schemas/three_d_secure"
},
"installments": {
"$ref": "#/components/schemas/installments"
},
"provider_data": {
"$ref": "#/components/schemas/provider_data"
},
"redirection": {
"$ref": "#/components/schemas/redirection_resource"
},
"provider_specific_data": {
"description": "This object contains provider specific objects, which contain data in key-value format. Use the <a href=\"https://developers.paymentsos.com/docs/providers.html#bodybuilder\" target=\"_blank\">Bodybuilder</a> to generate a sample request that includes a `provider_specific_data` object.",
"additionalProperties": {
"type": "object"
}
},
"originating_purchase_country": {
"description": "Country where the customer was located when making the purchase. (This is derived from the ip_address.) The country code is in <a href=\"https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3\" target=\"_blank\">ISO 3166-1 alpha-3</a> format.",
"type": "string"
},
"ip_address": {
"type": "string",
"description": "The IP address of the customer making the payment."
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
}
}
},
"new_charge": {
"description": "New charge",
"required": [
"payment_method"
],
"properties": {
"reconciliation_id": {
"description": "A unique ID generated by you, used for transaction reconciliation.",
"type": "string"
},
"payment_method": {
"oneOf": [
{
"$ref": "#/components/schemas/tokenized"
},
{
"$ref": "#/components/schemas/untokenized"
}
]
},
"three_d_secure_attributes": {
"$ref": "#/components/schemas/three_d_secure"
},
"installments": {
"$ref": "#/components/schemas/installments"
},
"merchant_site_url": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$",
"description": "The URL on your site to redirect your customer back to, after they leave the third-party site. The URL should be in 'http://' or 'https://' format."
},
"provider_specific_data": {
"description": "This object contains provider specific objects, which contain data in key-value format. Use the <a href=\"https://developers.paymentsos.com/docs/providers.html#bodybuilder\" target=\"_blank\">Bodybuilder</a> to generate a sample request that includes a `provider_specific_data` object.",
"type": "object",
"additionalProperties": {
"type": "object"
}
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
}
}
},
"new_credit": {
"description": "New Credit",
"required": [
"payment_method"
],
"properties": {
"reconciliation_id": {
"description": "A unique ID generated by you, used for transaction reconciliation.",
"type": "string"
},
"payment_method": {
"description": "This represents the Payment Method selected by the customer to pay.",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/tokenized"
}
]
},
"three_d_secure_attributes": {
"$ref": "#/components/schemas/three_d_secure"
},
"merchant_site_url": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$",
"description": "The URL on your site to redirect your customer back to, after they leave the third-party site. The URL should be in 'http://' or 'https://' format."
},
"provider_specific_data": {
"description": "This object contains provider specific objects, which contain data in key-value format. Use the <a href=\"https://developers.paymentsos.com/docs/providers.html#bodybuilder\" target=\"_blank\">Bodybuilder</a> to generate a sample request that includes a provider_specific_data' object.",
"additionalProperties": {
"type": "object"
}
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
}
}
},
"credit_resource": {
"description": "Credit",
"properties": {
"id": {
"description": "Identifier of the credit.",
"type": "string",
"pattern": "^[{(]?[0-9A-Fa-f]{8}[-]?([0-9A-Fa-f]{4}[-]?){3}[0-9A-Fa-f]{12}[)}]?$"
},
"result": {
"$ref": "#/components/schemas/result"
},
"amount": {
"$ref": "#/components/schemas/amount"
},
"created": {
"type": "string",
"description": "The date and time that the authorization was created.",
"format": "timestamp"
},
"reconciliation_id": {
"description": "A unique ID generated by you, used for transaction reconciliation.",
"type": "string"
},
"payment_method": {
"description": "This represents the Payment Method selected by the customer to pay.",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/tokenized_response"
}
],
"required": [
"href"
],
"properties": {
"href": {
"description": "The href link to the associated Payment Method.",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"three_d_secure_attributes": {
"$ref": "#/components/schemas/three_d_secure"
},
"provider_data": {
"$ref": "#/components/schemas/provider_data"
},
"provider_specific_data": {
"description": "This object contains provider specific objects, which contain data in key-value format. Use the <a href=\"https://developers.paymentsos.com/docs/providers.html#bodybuilder\" target=\"_blank\">Bodybuilder</a> to generate a sample request that includes a provider_specific_data' object.",
"additionalProperties": {
"type": "object"
}
},
"originating_purchase_country": {
"description": "Country where the customer was located when making the purchase. (This is derived from the ip_address.) The country code is in <a href=\"https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3\" target=\"_blank\">ISO 3166-1 alpha-3</a> format.",
"type": "string"
},
"ip_address": {
"type": "string",
"description": "The IP address of the customer making the payment."
},
"redirection": {
"$ref": "#/components/schemas/redirection_resource"
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
}
}
},
"authorization_resource": {
"description": "Authorization",
"properties": {
"id": {
"description": "Identifier of the authorization.",
"type": "string",
"pattern": "^[{(]?[0-9A-Fa-f]{8}[-]?([0-9A-Fa-f]{4}[-]?){3}[0-9A-Fa-f]{12}[)}]?$"
},
"result": {
"$ref": "#/components/schemas/result"
},
"amount": {
"$ref": "#/components/schemas/amount"
},
"created": {
"type": "string",
"description": "The date and time that the authorization was created.",
"format": "timestamp"
},
"reconciliation_id": {
"description": "A unique ID generated by you, used for transaction reconciliation.",
"type": "string"
},
"payment_method": {
"description": "This represents the Payment Method selected by the customer to pay.",
"type": "object",
"required": [
"href"
],
"properties": {
"href": {
"description": "The href link to the associated Payment Method. Note - The href is only included here for a payment method that is associated with a customer.\n",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
},
"oneOf": [
{
"$ref": "#/components/schemas/tokenized_response"
},
{
"$ref": "#/components/schemas/untokenized_response"
}
]
},
"three_d_secure_attributes": {
"$ref": "#/components/schemas/three_d_secure"
},
"installments": {
"$ref": "#/components/schemas/installments"
},
"provider_data": {
"$ref": "#/components/schemas/provider_data"
},
"redirection": {
"$ref": "#/components/schemas/redirection_resource"
},
"provider_specific_data": {
"description": "This object contains provider specific objects, which contain data in key-value format. Use the <a href=\"https://developers.paymentsos.com/docs/providers.html#bodybuilder\" target=\"_blank\">Bodybuilder</a> to generate a sample request that includes a `provider_specific_data` object.",
"additionalProperties": {
"type": "object"
}
},
"originating_purchase_country": {
"description": "Country where the customer was located when making the purchase. (This is derived from the ip_address.) The country code is in <a href=\"https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3\" target=\"_blank\">ISO 3166-1 alpha-3</a> format.",
"type": "string"
},
"ip_address": {
"type": "string",
"description": "The IP address of the customer making the payment."
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
}
}
},
"new_authorization": {
"description": "New authorization",
"required": [
"payment_method"
],
"properties": {
"reconciliation_id": {
"description": "A unique ID generated by you, used for transaction reconciliation.",
"type": "string"
},
"payment_method": {
"description": "This represents the Payment Method selected by the customer to pay.",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/tokenized"
},
{
"$ref": "#/components/schemas/untokenized"
}
]
},
"three_d_secure_attributes": {
"$ref": "#/components/schemas/three_d_secure"
},
"installments": {
"$ref": "#/components/schemas/installments"
},
"merchant_site_url": {
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$",
"description": "The URL on your site to redirect your customer back to, after they leave the third-party site. The URL should be in 'http://' or 'https://' format."
},
"provider_specific_data": {
"description": "This object contains provider specific objects, which contain data in key-value format. Use the <a href=\"https://developers.paymentsos.com/docs/providers.html#bodybuilder\" target=\"_blank\">Bodybuilder</a> to generate a sample request that includes a `provider_specific_data` object.",
"additionalProperties": {
"type": "object"
}
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
}
}
},
"result": {
"description": "Result of the transaction.",
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"description": "Status an be 'Pending', 'Succeed', or 'Failed'.",
"type": "string",
"enum": [
"Pending",
"Succeed",
"Failed"
]
},
"category": {
"description": "Response category.",
"type": "string"
},
"sub-category": {
"description": "Response sub-category.",
"type": "string"
},
"description": {
"description": "Response description.",
"type": "string"
}
}
},
"void_resource": {
"description": "Void details applicable to payments, orders or order items.",
"required": [
"id",
"created",
"result"
],
"properties": {
"id": {
"description": "Identifier of the void.",
"type": "string",
"pattern": "^[{(]?[0-9A-Fa-f]{8}[-]?([0-9A-Fa-f]{4}[-]?){3}[0-9A-Fa-f]{12}[)}]?$"
},
"created": {
"description": "The date and time that the void was created.",
"type": "string",
"format": "timestamp"
},
"provider_data": {
"$ref": "#/components/schemas/provider_data"
},
"result": {
"$ref": "#/components/schemas/result"
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
}
}
},
"capture_resource": {
"description": "Capture details.",
"properties": {
"id": {
"description": "Identifier of the capture.",
"type": "string",
"pattern": "^[{(]?[0-9A-Fa-f]{8}[-]?([0-9A-Fa-f]{4}[-]?){3}[0-9A-Fa-f]{12}[)}]?$"
},
"created": {
"description": "The date and time that the capture was created.",
"type": "string",
"format": "timestamp"
},
"reconciliation_id": {
"description": "A unique ID generated by you, used for transaction reconciliation.",
"type": "string"
},
"result": {
"$ref": "#/components/schemas/result"
},
"amount": {
"description": "dsds",
"$ref": "#/components/schemas/amount"
},
"provider_data": {
"$ref": "#/components/schemas/provider_data"
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
}
}
},
"refund_resource": {
"description": "Refund details.",
"properties": {
"id": {
"description": "Identifier of the refund.",
"type": "string",
"pattern": "^[{(]?[0-9A-Fa-f]{8}[-]?([0-9A-Fa-f]{4}[-]?){3}[0-9A-Fa-f]{12}[)}]?$"
},
"created": {
"description": "The date and time that the refund was created.",
"type": "string",
"format": "timestamp"
},
"reconciliation_id": {
"description": "A unique ID generated by you, used for transaction reconciliation.",
"type": "string"
},
"result": {
"$ref": "#/components/schemas/result"
},
"amount": {
"$ref": "#/components/schemas/amount"
},
"capture_id": {
"description": "Identifier of a Capture that is associated with this refund.",
"type": "string"
},
"reason": {
"description": "The refund reason.",
"type": "string"
},
"provider_data": {
"$ref": "#/components/schemas/provider_data"
},
"additional_details": {
"$ref": "#/components/schemas/additional_details"
}
}
},
"credit_card": {
"allOf": [
{
"$ref": "#/components/schemas/payment_method_request"
},
{
"required": [
"holder_name",
"card_number"
],
"properties": {
"holder_name": {
"description": "Name of the credit card holder.",
"type": "string"
},
"expiration_date": {
"description": "Credit card expiration date. Possible formats: mm-yyyy, mm-yy, mm.yyyy, mm.yy, mm/yy, mm/yyyy, mm yyyy, or mm yy.\n",
"type": "string",
"pattern": "^(0?[1-9]|1[0-2])(\\/|\\-|\\.| )\\d{2,4}$"
},
"identity_document": {
"description": "National identity document of the card holder.",
"properties": {
"type": {
"description": "Identity document type.",
"type": "string"
},
"number": {
"description": "Identity number.",
"type": "string",
"example": "123456789"
}
}
},
"credit_card_cvv": {
"description": "The CVV number on the card (3 or 4 digits) to be encrypted.\n\nSending this field returns an `encrypted_cvv` field, which\nexpires after three hours.\n\nThe `encrypted_cvv` field can be used in a Create\nAuthorization or Create Charge request, as the\n`credit_card_cvv` field.\n",
"type": "string",
"pattern": "^[0-9]{3}[0-9]?$"
},
"card_number": {
"description": "Credit card number.",
"type": "string",
"pattern": "\\d{8}|\\d{12,19}"
}
}
}
]
},
"three_d_secure": {
"description": "The result of a 3D Secure authentication, if you performed this check on your side.",
"type": "object",
"required": [
"encoding",
"xid",
"cavv",
"eci_flag"
],
"properties": {
"encoding": {
"description": "Encoding of the authentication - 'HEX' or 'BASE64'.",
"type": "string",
"enum": [
"HEX",
"BASE64"
]
},
"xid": {
"description": "The unique identifier for the transaction.",
"type": "string"
},
"cavv": {
"description": "The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction, provided by the card issuer.",
"type": "string"
},
"eci_flag": {
"description": "The Electronic Commerce Indicator (ECI) associated with the transaction.",
"type": "string"
}
}
},
"installments": {
"description": "Installment details for the transaction. Note - If the provider of the transaction does not support Installments, and the value is greater than 1, then the request will fail.",
"type": "object",
"required": [
"number_of_installments"
],
"properties": {
"number_of_installments": {
"description": "Number of installments.",
"type": "integer",
"minimum": 0
},
"first_payment_amount": {
"$ref": "#/components/schemas/amount"
},
"remaining_payments_amount": {
"$ref": "#/components/schemas/amount"
}
}
},
"provider_data": {
"description": "This is the response from the external provider who is processing the transaction.",
"type": "object",
"required": [
"provider_name",
"response_code"
],
"properties": {
"provider_name": {
"description": "Name of the external provider.",
"type": "string"
},
"response_code": {
"description": "Response code received.",
"type": "string"
},
"description": {
"description": "Description of the response code received.",
"type": "string"
},
"raw_response": {
"description": "The raw response received.",
"type": "string"
},
"avs_code": {
"type": "string",
"description": "Result of the AVS address check received. For more details see the\n <a href=\"https://en.wikipedia.org/wiki/Address_Verification_System\" target=\"_blank\">Address Verification System</a>\n"
},
"authorization_code": {
"type": "string",
"description": "The ID of the authorization, generated by the financial network."
},
"transaction_id": {
"type": "string",
"description": "The ID of the transaction in the provider's system."
},
"external_id": {
"type": "string",
"description": "The ID of the payment in the provider's system."
},
"documents": {
"type": "array",
"items": {
"type": "object",
"description": "Links to documents sent by the provider, in response to a request.",
"required": [
"descriptor"
],
"properties": {
"descriptor": {
"description": "The title of the document. For example, 'Receipt' or 'Invoice'.",
"type": "string",
"enum": [
"receipt",
"invoice",
"bank_list"
]
},
"content_type": {
"description": "The document type. For example, 'pdf' and/or 'html'.",
"type": "string",
"enum": [
"pdf",
"html",
"json"
]
},
"href": {
"description": "The href link/s to the document/s.",
"type": "string"
},
"content": {
"description": "The content of the document.",
"type": "string"
}
}
}
},
"additional_information": {
"type": "object",
"additionalProperties": {
"description": "Additional information from the provider in key/value pairs.",
"type": "string"
}
}
}
},
"redirection_resource": {
"description": "Redirection",
"required": [
"id",
"url",
"merchant_site_url"
],
"properties": {
"id": {
"description": "Identifier of the redirection.",
"type": "string",
"pattern": "^[{(]?[0-9A-Fa-f]{8}[-]?([0-9A-Fa-f]{4}[-]?){3}[0-9A-Fa-f]{12}[)}]?$"
},
"created": {
"description": "The date and time that the redirection was created.",
"type": "string",
"format": "timestamp"
},
"merchant_site_url": {
"description": "The URL on your site to redirect your customer back to, after they leave the third-party site. The URL should be in 'http://' or 'https://' format.",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
},
"url": {
"description": "The third-party site URL that you should redirect your customer to.",
"type": "string",
"pattern": "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
}
}
},
"amount": {
"type": "integer",
"format": "integer",
"minimum": 0,
"description": "Amount must be greater than 0. The amount is formatted in <a href=\"https://developers.paymentsos.com/docs/minor-currency-units.html\" target=\"_blank\">Minor Units</a> format.",
"example": 1000
},
"currency": {
"description": "The three character currency code in <a href=\"https://en.wikipedia.org/wiki/ISO_4217\" target=\"_blank\">ISO-4217</a> format.",
"externalDocs": {
"description": "ISO-4217",
"url": "http://www.currency-iso.org/en/home/tables/table-a1.html"
},
"type": "string",
"pattern": "^[A-Z]{3}$",
"example": "USD"
},
"order_id": {
"description": "Identifier of the order. If you configured webhooks, then the order id is returned in the\n<a href=\"https://developers.paymentsos.com/docs/webhooks.html#webhooks-notifications-structure\" target=\"_blank\">webhook notification</a> as well.\n",
"example": 233503,
"type": "string"
},
"statement_soft_descriptor": {
"type": "string",
"description": "The transaction description that will appear in the customer's credit card statement, which identifies the merchant and payment. Check the relevant provider sites to see if this field is supported. If so, see the required content and format.\n**Note**: This transaction description is generated by you. Providing a clear description helps your customers recognize their transactions, and reduces chargebacks.\n",
"example": "RunClub 5km race ticket"
},
"address": {
"type": "object",
"description": "Address.",
"properties": {
"country": {
"description": "Country code in <a href=\"https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3\" target=\"_blank\">ISO 3166-1 alpha-3</a> format.",
"externalDocs": {
"description": "ISO-3166",
"url": "https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3"
},
"type": "string",
"pattern": "^[A-Z]{3}$",
"example": "USA"
},
"state": {
"description": "State.",
"type": "string",
"example": "TX"
},
"city": {
"description": "City.",
"type": "string",
"example": "Greenville"
},
"line1": {
"description": "Address line 1.",
"type": "string",
"example": "10705 Old Mill Rd"
},
"line2": {
"description": "Address line 2.",
"type": "string",
"example": "11605 Young Mill Rd"
},
"zip_code": {
"description": "Zip code / postal number.",
"type": "string",
"example": "75402-3435"
},
"title": {
"description": "Title ('salutation').",
"type": "string",
"example": "Dr."
},
"first_name": {
"description": "First name.",
"type": "string",
"example": "John"
},
"last_name": {
"description": "Last name (surname).",
"type": "string",
"example": "Travolta"
},
"phone": {
"description": "Phone number including the country code.",
"type": "string",
"example": 13301303330
},
"email": {
"description": "Email address.",
"type": "string",
"example": "john.travolta@johntravolta.com"
}
}
},
"additional_details": {
"type": "object",
"description": "Optional additional data stored in key/value pairs.",
"additionalProperties": {
"type": "string",
"example": "The details you specify"
}
},
"payment_method": {
"description": "A Payment Method represents a credit card associated with a customer, stored in our system with the customer's agreement. Note - Only tokenized payment methods can be associated to customers.",
"type": "object",
"required": [
"href",
"token_type",
"type",
"token",
"created",
"fingerprint"
],
"properties": {
"href": {
"type": "string",
"description": "The href link to the associated Payment Method. Note - The href is only included here for a payment method that is associated with a customer."
},
"type": {
"type": "string",
"enum": [
"tokenized"
]
},
"token_type": {
"type": "string",
"enum": [
"credit_card"
]
},
"token": {
"type": "string",
"description": "The token representing the payment method (created using the create token request)."
},
"created": {
"type": "string",
"format": "timestamp"
},
"customer": {
"type": "string",
"description": "The href link to the customer associated with this payment method."
},
"additional_details": {
"description": "Additional details recorded by the merchant in key/value pairs.",
"additionalProperties": {
"type": "string"
}
},
"fingerprint": {
"type": "string",
"description": "Uniquely identifies this particular card number. You can use this attribute to check whether two tokens represent the same card number."
},
"identity_document": {
"description": "National identity document of the card holder.",
"type": "object",
"properties": {
"type": {
"description": "Identity document type.",
"type": "string"
},
"number": {
"description": "Identity number.",
"type": "string"
}
}
}
}
},
"payment_method_request": {
"description": "Payment method details.",
"required": [
"token_type"
],
"properties": {
"token_type": {
"description": "The type of token. Possible value - 'credit_card'.",
"type": "string",
"enum": [
"credit_card"
]
},
"billing_address": {
"$ref": "#/components/schemas/address"
},
"additional_details": {
"description": "Optional additional data stored with your token in key/value pairs.",
"additionalProperties": {
"type": "string"
}
}
}
},
"tokenized_response": {
"description": "An object representing a tokenized payment method in a request.",
"allOf": [
{
"$ref": "#/components/schemas/payment_method"
},
{
"required": [
"token",
"holder_name",
"expiration_date",
"last_4_digits"
],
"properties": {
"token": {
"description": "The token representing the payment method (created using the create token request).",
"type": "string"
},
"type": {
"description": "The type of payment method. Possible value: `tokenized`.\n"
},
"country_code": {
"description": "The country where the credit card was issued, in <a href=\"https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3\" target=\"_blank\">ISO 3166-1 alpha-3 </a> format.",
"externalDocs": {
"description": "ISO-3166",
"url": "https://www.iso.org/obp/ui/"
},
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"billing_address": {
"$ref": "#/components/schemas/address"
},
"holder_name": {
"description": "Name of the credit card holder.",
"type": "string"
},
"expiration_date": {
"description": "\"Credit card expiration date.\"\n\"Possible formats: mm-yyyy, mm-yy, mm.yyyy, mm.yy, mm/yy, mm/yyyy, mm yyyy, or mm yy.\"\n",
"type": "string",
"pattern": "^(0?[1-9]|1[0-2])(\\/|\\-|\\.| )\\d{2,4}$"
},
"last_4_digits": {
"description": "Masked credit card number (last four digits).",
"type": "string"
},
"pass_luhn_validation": {
"$ref": "#/components/schemas/pass_luhn_validation"
},
"bin_number": {
"description": "\"The first six digits of the credit card number.\"\n\"'BIN' = Bank Identification Number. (Also known as 'IIN'=Issuer Identification Number.)\"\n",
"type": "string",
"pattern": "^\\d{6}$"
},
"vendor": {
"description": "The vendor of the credit card.",
"type": "string"
},
"issuer": {
"description": "The issuer of the credit card.",
"type": "string"
},
"card_type": {
"description": "The type of the credit card.",
"type": "string"
},
"level": {
"description": "The credit card level (e.g. PREPAID, CLASSIC).",
"type": "string"
}
}
}
]
},
"untokenized_response": {
"description": "An object representing an untokenized payment method in a request.",
"required": [
"source_type"
],
"properties": {
"source_type": {
"description": "The type of alternative payment method selected by the customer\n to pay. Use the <a href=\"https://developers.paymentsos.com/docs/providers.html#bodybuilder\" target=\"_blank\">Bodybuilder</a> to generate a sample request that includes the values you need pass in the field.",
"type": "string"
},
"type": {
"description": "The type of payment method. Possible value: `untokenized`.\n",
"type": "string"
},
"vendor": {
"type": "string",
"description": "The vendor processing the alternative payment. Use the <a href=\"https://developers.paymentsos.com/docs/providers.html#bodybuilder\" target=\"_blank\">Bodybuilder</a> to generate a sample request that includes the values you need pass in the field.\n"
},
"additional_details": {
"description": "Optional additional details in key/value pairs.",
"additionalProperties": {
"type": "string"
}
}
}
},
"tokenized": {
"description": "An object representing a tokenized payment method in a request.",
"type": "object",
"required": [
"token",
"type"
],
"properties": {
"token": {
"description": "The token representing the payment method, (created using the create token request).",
"type": "string"
},
"credit_card_cvv": {
"description": "This can either be a string of '3 to 4 numbers', or the value of the 'encrypted_cvv' field returned from a 'create token' request. The 'encrypted_cvv' field expires after three hours.",
"type": "string"
},
"type": {
"description": "The type of payment method. Possible value: `tokenized`.\n",
"type": "string"
}
}
},
"untokenized": {
"description": "An object representing an untokenized payment method in a request.",
"type": "object",
"required": [
"source_type",
"type"
],
"properties": {
"source_type": {
"description": "The type of alternative payment method selected by the customer to pay. Possible values - 'bank_transfer' or 'cash'.",
"type": "string"
},
"type": {
"description": "The type of payment method. Possible value: `untokenized`.\n"
},
"vendor": {
"type": "string",
"description": "The vendor processing the alternative payment."
},
"additional_details": {
"description": "Optional additional details in key/value pairs.",
"additionalProperties": {
"type": "string"
}
}
}
},
"token": {
"required": [
"token",
"created",
"type",
"token_type",
"state"
],
"properties": {
"token": {
"description": "A token represents a customer's credit card number, selected by the customer to pay.",
"type": "string"
},
"created": {
"description": "The date and time that the token was created.",
"type": "string",
"format": "timestamp"
},
"token_type": {
"description": "The type of token. Possible value - 'credit_card'.",
"type": "string"
},
"type": {
"description": "The card's representation, as it will be used in an authorization or charge request.",
"type": "string",
"enum": [
"tokenized"
]
},
"pass_luhn_validation": {
"$ref": "#/components/schemas/pass_luhn_validation"
},
"state": {
"description": "Reflects the token's usage. The state can be one of the following:\n* `valid`: token has been successfully created and can be used. Only applies to tokens created in API version 1.1.0 or below.\n\nThe following states apply to version 1.2.0 or higher:\n* `created`: token has been successfully created but has not yet been used or assigned to a customer.\n\n* `used`: token has been used in a successful authorize or charge request.\n\n* `assigned`: the token is assigned to a customer. The token will remain in this state also if it is used in a new authorize or charge request.\n",
"type": "string",
"enum": [
"valid",
"created",
"used",
"assigned"
]
},
"bin_number": {
"type": "string",
"description": "The initial four to six numbers that appear on the card.",
"example": 123456
},
"vendor": {
"description": "The name of the credit card corporation.",
"example": "MasterCard",
"type": "string"
},
"issuer_name": {
"type": "string",
"description": "The name of the bank that issued the card.",
"example": "Bank of America"
},
"card_type": {
"type": "string",
"description": "The type of card.",
"example": "credit"
},
"level": {
"type": "string",
"description": "The level of benefits or services available with the card.",
"example": "CLASSIC"
},
"country_code": {
"type": "string",
"description": "The 3-digit country code defined in <a href=\"https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3\" target=\"_blank\">ISO 3166-1 alpha-3</a> format, identifying the country in which the card was issued.",
"example": "USA"
}
}
},
"error_model": {
"required": [
"description",
"category"
],
"properties": {
"category": {
"type": "string",
"description": "Error code."
},
"description": {
"type": "string",
"description": "Error message for the developer."
},
"more_info": {
"type": "string",
"description": "More info about the error, can include link to the documentation."
}
}
},
"pass_luhn_validation": {
"description": "When token_type is 'credit_card', then this indicates if the credit card number passed the luhn validation.\nRead more about the <a href=\"https://en.wikipedia.org/wiki/Luhn_algorithm\" target=\"_blank\">Luhn Algorithm</a>.\n",
"externalDocs": {
"description": "Luhn Algorithm",
"url": "https://en.wikipedia.org/wiki/Luhn_algorithm"
},
"type": "boolean"
}
}
}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment