{ "openapi": "3.0.1", "info": { "title": "SumUp REST API", "version": "1.0.0", "description": "SumUp’s REST API operates with [JSON](https://www.json.org/json-en.html) HTTP requests and responses. The request bodies are sent through resource-oriented URLs and use the standard [HTTP response codes](https://developer.mozilla.org/docs/Web/HTTP/Status).\n\nYou can experiment and work on your integration in a sandbox that doesn't affect your regular data and doesn't process real transactions. To create a sandbox merchant account visit the [dashboard](https://me.sumup.com/settings/developer). To use the sandbox when interacting with SumUp APIs [create an API](https://me.sumup.com/settings/api-keys) key and use it for [authentication](https://developer.sumup.com/api/authentication).\n", "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } }, "servers": [ { "url": "https://api.sumup.com", "description": "Production server" } ], "paths": { "/v0.1/merchants/{merchant_code}/payment-methods": { "get": { "operationId": "GetPaymentMethods", "summary": "Get available payment methods", "description": "Get payment methods available for the given merchant to use with a checkout.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "The SumUp merchant code.", "required": true, "schema": { "type": "string", "example": "M1234" } }, { "name": "amount", "in": "query", "description": "The amount for which the payment methods should be eligible, in major units. Note that currency must also be provided when filtering by amount.", "required": false, "schema": { "type": "number", "example": 9.99 } }, { "name": "currency", "in": "query", "description": "The currency for which the payment methods should be eligible.", "required": false, "schema": { "type": "string", "example": "EUR" } } ], "responses": { "200": { "description": "Available payment methods", "content": { "application/json": { "schema": { "type": "object", "properties": { "available_payment_methods": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "description": "The ID of the payment method.", "type": "string", "example": "qr_code_pix" } } } } } }, "examples": { "success": { "description": "Available payment methods", "value": { "available_payment_methods": [ { "id": "apple_pay" }, { "id": "blik" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailsError" }, "examples": { "Invalid_Parameter": { "description": "One or more of the parameters are invalid.", "value": { "failed_constraints": [ { "message": "Currency must also be specified when filtering by amount", "reference": "currency" } ], "status": 400, "title": "Bad Request" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "payments" ] } ], "tags": [ "Checkouts" ], "x-codegen": { "method_name": "list_available_payment_methods" }, "x-scopes": [ "payments" ] } }, "/v0.1/checkouts": { "post": { "operationId": "CreateCheckout", "summary": "Create a checkout", "description": "Creates a new payment checkout resource. The unique `checkout_reference` created by this request, is used for further manipulation of the checkout.\n\nFor 3DS checkouts, add the `redirect_url` parameter to your request body schema.\n\nFollow by processing a checkout to charge the provided payment instrument.\n", "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCreateRequest" }, "examples": { "Checkout": { "description": "Standard request body for creating a checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MDUDGLR9", "description": "Purchase", "id": "2b79757a-de87-4a2e-90e4-b17c947c730d", "status": "PAID", "date": "2020-02-29T10:56:56+00:00", "merchant_name": "John Doe LTD", "redirect_url": "https://sumup.com" } }, "Checkout3DS": { "description": "Create a 3DS checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MH4H92C7", "description": "Purchase", "return_url": "http://example.com/", "customer_id": "831ff8d4cd5958ab5670", "redirect_url": "https://mysite.com/completed_purchase" } }, "CheckoutAPM": { "description": "Create an Alternative Payment Method checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "redirect_url": "https://mysite.com/completed_purchase" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" }, "examples": { "Checkout": { "description": "Standard response body for a successfully created checkout", "value": { "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MCNPLE22", "merchant_country": "DE", "description": "My Checkout", "return_url": "http://example.com", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2020-02-29T10:56:56+00:00", "customer_id": "831ff8d4cd5958ab5670", "mandate": { "type": "recurrent", "status": "active", "merchant_code": "MDASYTPD" }, "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345", "internal_id": 0 } ] } }, "Checkout3DS": { "description": "Response body for a successfully created 3DS checkout", "value": { "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "description": "My Checkout", "return_url": "http://example.com", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2020-02-29T10:56:56+00:00", "customer_id": "831ff8d4cd5958ab5670", "redirect_url": "https://mysite.com/completed_purchase", "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345", "internal_id": 0 } ] } }, "CheckoutAPM": { "description": "Response body for APMs, including Blik, iDeal, ...", "value": { "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MCNPLE22", "description": "My Checkout", "return_url": "http://example.com", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2021-06-29T11:08:36.000+00:00", "merchant_name": "My company", "merchant_country": "DE", "redirect_url": "https://sumup.com", "purpose": "CHECKOUT", "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345", "internal_id": 0 } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorExtended" }, "examples": { "Missing_Parameter": { "description": "A required parameter is missing.", "value": { "message": "Validation error", "error_code": "MISSING", "param": "pay_to_email" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have the required permission for making this request.", "value": { "error_message": "checkout_payments_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Existing_Checkout": { "description": "A resource with the specified parameters already exists on the server.", "value": { "error_code": "DUPLICATED_CHECKOUT", "message": "Checkout with this checkout reference and pay to email already exists" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "payments" ] } ], "tags": [ "Checkouts" ], "x-codegen": { "method_name": "create" }, "x-scopes": [ "payments" ] }, "get": { "operationId": "ListCheckouts", "summary": "List checkouts", "description": "Lists created checkout resources according to the applied `checkout_reference`.", "parameters": [ { "name": "checkout_reference", "in": "query", "description": "Filters the list of checkout resources by the unique ID of the checkout.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSuccess" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "payments" ] } ], "tags": [ "Checkouts" ], "x-codegen": { "method_name": "list" }, "x-scopes": [ "payments" ] } }, "/v0.1/checkouts/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "Unique ID of the checkout resource.", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "GetCheckout", "summary": "Retrieve a checkout", "description": "Retrieves an identified checkout resource. Use this request after processing a checkout to confirm its status and inform the end user respectively.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSuccess" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "payments" ] } ], "tags": [ "Checkouts" ], "x-codegen": { "method_name": "get" }, "x-scopes": [ "payments" ] }, "put": { "operationId": "ProcessCheckout", "summary": "Process a checkout", "description": "Processing a checkout will attempt to charge the provided payment instrument for the amount of the specified checkout resource initiated in the `Create a checkout` endpoint.\n\nFollow this request with `Retrieve a checkout` to confirm its status.\n", "requestBody": { "description": "Details of the payment instrument for processing the checkout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutProcessMixin" }, "examples": { "ProcessCard": { "description": "Process a checkout with a card", "value": { "payment_type": "card", "installments": 1, "mandate": { "type": "recurrent", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36", "user_ip": "172.217.169.174" }, "card": { "type": "VISA", "name": "John Doe", "number": "1234567890123456", "expiry_year": "2023", "expiry_month": "01", "cvv": "123", "zip_code": "12345", "last_4_digits": "3456" } } }, "ProcessToken": { "description": "Process a checkout with a token", "value": { "payment_type": "card", "installments": 1, "token": "ba85dfee-c3cf-48a6-84f5-d7d761fbba50", "customer_id": "MEDKHDTI" } }, "ProcessBoleto": { "description": "Process a checkout with Boleto", "value": { "payment_type": "boleto", "personal_details": { "email": "user@example.com", "first_name": "John", "last_name": "Doe", "tax_id": "423.378.593-47", "address": { "country": "BR", "city": "São Paulo", "line1": "Rua Gilberto Sabino, 215", "state": "SP", "postal_code": "05425-020" } } } }, "ProcessiDeal": { "description": "Process a checkout with iDeal", "value": { "payment_type": "ideal", "personal_details": { "email": "user@example.com", "first_name": "John", "last_name": "Doe", "address": { "country": "NL" } } } }, "ProcessBancontact": { "description": "Process a checkout with Bancontact", "value": { "payment_type": "bancontact", "personal_details": { "email": "user@example.com", "first_name": "John", "last_name": "Doe", "address": { "country": "BE" } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSuccess" }, "examples": { "CheckoutSuccessCard": { "description": "Successfully processed checkout with a card", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MH4H92C7", "description": "Purchase", "return_url": "http://example.com", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2020-02-29T10:56:56+00:00", "customer_id": "831ff8d4cd5958ab5670", "mandate": { "type": "recurrent", "status": "active", "merchant_code": "MDASYTPD" }, "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "053201", "internal_id": 1763892018 } ], "transaction_code": "TEENSK4W2K", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4" } }, "CheckoutSuccessToken": { "description": "Successfully processed checkout with a token", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MH4H92C7", "description": "Purchase with token", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "transaction_code": "TEENSK4W2K", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "merchant_name": "Sample Merchant", "redirect_url": "https://mysite.com/completed_purchase", "customer_id": "831ff8d4cd5958ab5670", "payment_instrument": { "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc" }, "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "053201", "internal_id": 1763892018 } ] } }, "CheckoutSuccessBoleto": { "description": "Successfully processed checkout with Boleto", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "BRL", "pay_to_email": "user@example.com", "merchant_code": "MH4H92C7", "description": "Boleto checkout", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PENDING", "date": "2021-07-06T12:34:02.000+00:00", "merchant_name": "Sample shop", "boleto": { "barcode": "34191090081790614310603072340007886840000000200", "url": "https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto" }, "redirect_url": "https://website.com", "purpose": "CHECKOUT", "transactions": [ { "id": "debd2986-9852-4e86-8a8e-7ea9c87dd679", "transaction_code": "TEN3E696NP", "merchant_code": "MH4H92C9", "amount": 10.1, "vat_amount": 6, "tip_amount": 3, "currency": "BRL", "timestamp": "2021-07-06T12:34:16.460+00:00", "status": "PENDING", "payment_type": "BOLETO", "entry_mode": "BOLETO", "installments_count": 1, "internal_id": 1763892018 } ] } }, "CheckoutSuccessiDeal": { "description": "Successfully processed checkout with iDeal", "value": { "next_step": { "url": "https://r3.girogate.de/ti/simideal", "method": "GET", "payload": { "tx": "961473700", "rs": "ILnaUeQTKJ184fVrjGILrLjePX9E4rmz", "cs": "c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5" }, "full": "https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5", "mechanism": [ "browser" ] } } }, "CheckoutSuccessBancontact": { "description": "Successfully processed checkout with Bancontact", "value": { "next_step": { "url": "https://r3.girogate.de/ti/simbcmc", "method": "GET", "payload": { "tx": "624788471", "rs": "5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB", "cs": "697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc" }, "full": "https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc", "mechanism": [ "browser" ] } } } } } } }, "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAccepted" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorExtended" }, { "type": "array", "description": "List of error messages.", "items": { "$ref": "#/components/schemas/ErrorExtended" } } ] }, "examples": { "Invalid_Parameter": { "description": "A required parameter has an invalid value.", "value": { "message": "Validation error", "error_code": "INVALID", "param": "card.expiry_year" } }, "Multiple_Invalid_Parameters": { "description": "Multiple required parameters have invalid values.", "value": [ { "error_code": "INVALID", "message": "Validation error", "param": "card.name" }, { "error_code": "INVALID", "message": "Validation error", "param": "card.number" }, { "error_code": "INVALID", "message": "Validation error", "param": "card.expiry_year" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Checkout_Processed": { "description": "The identified checkout resource is already processed.", "value": { "error_code": "CHECKOUT_PROCESSED", "message": "Checkout is already processed" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Checkouts" ], "x-codegen": { "method_name": "process" }, "x-scopes": [] }, "delete": { "operationId": "DeactivateCheckout", "summary": "Deactivate a checkout", "description": "Deactivates an identified checkout resource. If the checkout has already been processed it can not be deactivated.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "Details of the deleted checkout.", "type": "object", "properties": { "checkout_reference": { "description": "Unique ID of the payment checkout specified by the client application when creating the checkout resource.", "type": "string", "maxLength": 90 }, "id": { "description": "Unique ID of the checkout resource.", "type": "string", "readOnly": true }, "amount": { "description": "Amount of the payment.", "type": "number", "format": "float" }, "currency": { "$ref": "#/components/schemas/Currency" }, "pay_to_email": { "description": "Email address of the registered user (merchant) to whom the payment is made.", "type": "string", "format": "email", "deprecated": true, "x-deprecation-notice": "`pay_to_email` is deprecated, use `merchant_code` instead." }, "merchant_code": { "description": "Unique identifying code of the merchant profile.", "type": "string" }, "description": { "description": "Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.", "type": "string" }, "purpose": { "description": "Purpose of the checkout creation initially", "type": "string", "enum": [ "SETUP_RECURRING_PAYMENT", "CHECKOUT" ] }, "status": { "description": "Current status of the checkout.", "type": "string", "enum": [ "EXPIRED" ], "readOnly": true }, "date": { "description": "Date and time of the creation of the payment checkout. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.", "type": "string", "format": "date-time", "example": "2020-02-29T10:56:56+00:00", "readOnly": true }, "valid_until": { "description": "Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.", "type": "string", "format": "date-time", "example": "2020-02-29T10:56:56+00:00", "nullable": true, "readOnly": true }, "merchant_name": { "description": "Merchant name", "type": "string" }, "merchant_country": { "description": "The merchant's country", "type": "string" }, "transactions": { "description": "List of transactions related to the payment.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/TransactionMixinBase" }, { "$ref": "#/components/schemas/TransactionMixinCheckout" } ] }, "readOnly": true, "uniqueItems": true } } }, "examples": { "DeletedCheckout": { "description": "Response body for a successfully deactivated checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "id": "817340ce-f1d9-4609-b90a-6152f8ee267j", "amount": 2, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MH4H92C7", "description": "Deletion example", "purpose": "CHECKOUT", "status": "EXPIRED", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2020-02-29T10:56:56+00:00", "merchant_name": "Sample Merchant", "transactions": [] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Checkout_Processed": { "description": "The identified checkout resource is already processed.", "value": { "error_code": "CHECKOUT_PROCESSED", "message": "Checkout is already processed" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "payments" ] } ], "tags": [ "Checkouts" ], "x-codegen": { "method_name": "deactivate" }, "x-scopes": [ "payments" ] } }, "/v0.1/customers": { "post": { "operationId": "CreateCustomer", "summary": "Create a customer", "description": "Creates a new saved customer resource which you can later manipulate and save payment instruments to.", "requestBody": { "description": "Details of the customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Existing_Customer": { "description": "A resource with the specified identifier already exists on the server.", "value": { "message": "Customer already exists", "error_code": "CUSTOMER_ALREADY_EXISTS" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "payment_instruments" ] } ], "tags": [ "Customers" ], "x-codegen": { "method_name": "create" }, "x-scopes": [ "payment_instruments" ] } }, "/v0.1/customers/{customer_id}": { "parameters": [ { "name": "customer_id", "in": "path", "description": "Unique ID of the saved customer resource.", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "GetCustomer", "summary": "Retrieve a customer", "description": "Retrieves an identified saved customer resource through the unique `customer_id` parameter, generated upon customer creation.", "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "payment_instruments" ] } ], "tags": [ "Customers" ], "x-codegen": { "method_name": "get" }, "x-scopes": [ "payment_instruments" ] }, "put": { "operationId": "UpdateCustomer", "summary": "Update a customer", "description": "Updates an identified saved customer resource's personal details.\n\nThe request only overwrites the parameters included in the request, all other parameters will remain with their initially assigned values.\n", "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "personal_details": { "$ref": "#/components/schemas/PersonalDetails" } } } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "payment_instruments" ] } ], "tags": [ "Customers" ], "x-codegen": { "method_name": "update" }, "x-scopes": [ "payment_instruments" ] } }, "/v0.1/customers/{customer_id}/payment-instruments": { "parameters": [ { "name": "customer_id", "in": "path", "description": "Unique ID of the saved customer resource.", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "ListPaymentInstruments", "summary": "List payment instruments", "description": "Lists all payment instrument resources that are saved for an identified customer.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentInstrumentResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "payment_instruments" ] } ], "tags": [ "Customers" ], "x-codegen": { "method_name": "list_payment_instruments" }, "x-scopes": [ "payment_instruments" ] } }, "/v0.1/customers/{customer_id}/payment-instruments/{token}": { "parameters": [ { "name": "customer_id", "in": "path", "description": "Unique ID of the saved customer resource.", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "path", "description": "Unique token identifying the card saved as a payment instrument resource.", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "DeactivatePaymentInstrument", "summary": "Deactivate a payment instrument", "description": "Deactivates an identified card payment instrument resource for a customer.", "responses": { "204": { "description": "No Content", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "NoBody": { "value": {} } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "payment_instruments" ] } ], "tags": [ "Customers" ], "x-codegen": { "method_name": "deactivate_payment_instrument" }, "x-scopes": [ "payment_instruments" ] } }, "/v0.1/me/refund/{txn_id}": { "parameters": [ { "name": "txn_id", "in": "path", "description": "Unique ID of the transaction.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "RefundTransaction", "summary": "Refund a transaction", "description": "Refunds an identified transaction either in full or partially.", "requestBody": { "description": "", "content": { "application/json": { "schema": { "description": "Optional amount for partial refunds of transactions.", "type": "object", "properties": { "amount": { "description": "Amount to be refunded. Eligible amount can't exceed the amount of the transaction and varies based on country and currency. If you do not specify a value, the system performs a full refund of the transaction.", "type": "number", "format": "float" } } } } } }, "responses": { "204": { "description": "No Content", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "NoBody": { "value": {} } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Transaction_Not_Refundable": { "description": "The state of the identified transaction resource does not permit the requested operation.", "value": { "error_code": "CONFLICT", "message": "The transaction is not refundable in its current state" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "payments" ] } ], "tags": [ "Transactions" ], "x-codegen": { "method_name": "refund" }, "x-scopes": [ "payments" ] } }, "/v2.1/merchants/{merchant_code}/transactions": { "get": { "operationId": "GetTransactionV2.1", "summary": "Retrieve a transaction", "description": "Retrieves the full details of an identified transaction. The transaction resource is identified by a query parameter and *one* of following parameters is required:\n\n * `id`\n * `internal_id`\n * `transaction_code`\n * `foreign_transaction_id`\n * `client_transaction_id`\n", "parameters": [ { "name": "merchant_code", "in": "path", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "id", "in": "query", "description": "Retrieves the transaction resource with the specified transaction ID (the `id` parameter in the transaction resource).", "required": false, "schema": { "type": "string" } }, { "name": "internal_id", "in": "query", "description": "Retrieves the transaction resource with the specified internal transaction ID (the `internal_id` parameter in the transaction resource).", "required": false, "schema": { "type": "string" } }, { "name": "transaction_code", "in": "query", "description": "Retrieves the transaction resource with the specified transaction code.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionFull" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "transactions.history" ] } ], "tags": [ "Transactions" ], "x-codegen": { "method_name": "get" }, "x-scopes": [ "transactions.history" ] } }, "/v0.1/me/transactions": { "get": { "operationId": "GetTransaction", "summary": "Retrieve a transaction", "description": "Retrieves the full details of an identified transaction. The transaction resource is identified by a query parameter and *one* of following parameters is required:\n\n * `id`\n * `internal_id`\n * `transaction_code`\n * `foreign_transaction_id`\n * `client_transaction_id`\n", "parameters": [ { "name": "id", "in": "query", "description": "Retrieves the transaction resource with the specified transaction ID (the `id` parameter in the transaction resource).", "required": false, "schema": { "type": "string" } }, { "name": "internal_id", "in": "query", "description": "Retrieves the transaction resource with the specified internal transaction ID (the `internal_id` parameter in the transaction resource).", "required": false, "schema": { "type": "string" } }, { "name": "transaction_code", "in": "query", "description": "Retrieves the transaction resource with the specified transaction code.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionFull" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } } }, "deprecated": true, "security": [ { "apiKey": [] }, { "oauth2": [ "transactions.history" ] } ], "tags": [ "Transactions" ], "x-codegen": { "method_name": "get_deprecated" }, "x-scopes": [ "transactions.history" ] } }, "/v2.1/merchants/{merchant_code}/transactions/history": { "get": { "operationId": "ListTransactionsV2.1", "summary": "List transactions", "description": "Lists detailed history of all transactions associated with the merchant profile.", "parameters": [ { "name": "merchant_code", "in": "path", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "transaction_code", "in": "query", "description": "Retrieves the transaction resource with the specified transaction code.", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Specifies the order in which the returned results are displayed.", "schema": { "type": "string", "default": "ascending", "enum": [ "ascending", "descending" ] } }, { "name": "limit", "in": "query", "description": "Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results.", "schema": { "type": "integer" } }, { "name": "users", "in": "query", "description": "Filters the returned results by user email.", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "email" } } }, { "name": "statuses", "in": "query", "description": "Filters the returned results by the specified list of final statuses of the transactions.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "SUCCESSFUL", "CANCELLED", "FAILED", "REFUNDED", "CHARGE_BACK" ] } } }, { "name": "payment_types", "in": "query", "description": "Filters the returned results by the specified list of payment types used for the transactions.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "CASH", "POS", "ECOM", "BALANCE", "MOTO", "BOLETO", "UNKNOWN" ] } } }, { "name": "types", "in": "query", "description": "Filters the returned results by the specified list of transaction types.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "PAYMENT", "REFUND", "CHARGE_BACK" ] } } }, { "name": "changes_since", "in": "query", "description": "Filters the results by the latest modification time of resources and returns only transactions that are modified *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "newest_time", "in": "query", "description": "Filters the results by the creation time of resources and returns only transactions that are created *before* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "newest_ref", "in": "query", "description": "Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *smaller* than the specified value. This parameters supersedes the `newest_time` parameter (if both are provided in the request).", "required": false, "schema": { "type": "string" } }, { "name": "oldest_time", "in": "query", "description": "Filters the results by the creation time of resources and returns only transactions that are created *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "oldest_ref", "in": "query", "description": "Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *greater* than the specified value. This parameters supersedes the `oldest_time` parameter (if both are provided in the request).", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionHistory" } }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "transactions.history" ] } ], "tags": [ "Transactions" ], "x-codegen": { "method_name": "list" }, "x-scopes": [ "transactions.history" ] } }, "/v0.1/me/transactions/history": { "get": { "operationId": "ListTransactions", "summary": "List transactions", "description": "Lists detailed history of all transactions associated with the merchant profile.", "parameters": [ { "name": "transaction_code", "in": "query", "description": "Retrieves the transaction resource with the specified transaction code.", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Specifies the order in which the returned results are displayed.", "schema": { "type": "string", "default": "ascending", "enum": [ "ascending", "descending" ] } }, { "name": "limit", "in": "query", "description": "Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results.", "schema": { "type": "integer" } }, { "name": "users", "in": "query", "description": "Filters the returned results by user email.", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "email" } } }, { "name": "statuses", "in": "query", "description": "Filters the returned results by the specified list of final statuses of the transactions.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "SUCCESSFUL", "CANCELLED", "FAILED", "REFUNDED", "CHARGE_BACK" ] } } }, { "name": "payment_types", "in": "query", "description": "Filters the returned results by the specified list of payment types used for the transactions.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "CASH", "POS", "ECOM", "BALANCE", "MOTO", "BOLETO", "UNKNOWN" ] } } }, { "name": "types", "in": "query", "description": "Filters the returned results by the specified list of transaction types.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "PAYMENT", "REFUND", "CHARGE_BACK" ] } } }, { "name": "changes_since", "in": "query", "description": "Filters the results by the latest modification time of resources and returns only transactions that are modified *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "newest_time", "in": "query", "description": "Filters the results by the creation time of resources and returns only transactions that are created *before* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "newest_ref", "in": "query", "description": "Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *smaller* than the specified value. This parameters supersedes the `newest_time` parameter (if both are provided in the request).", "required": false, "schema": { "type": "string" } }, { "name": "oldest_time", "in": "query", "description": "Filters the results by the creation time of resources and returns only transactions that are created *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "oldest_ref", "in": "query", "description": "Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *greater* than the specified value. This parameters supersedes the `oldest_time` parameter (if both are provided in the request).", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionHistory" } }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } } }, "deprecated": true, "security": [ { "apiKey": [] }, { "oauth2": [ "transactions.history" ] } ], "tags": [ "Transactions" ], "x-codegen": { "method_name": "list_deprecated" }, "x-scopes": [ "transactions.history" ] } }, "/v0.1/me": { "get": { "operationId": "GetAccount", "summary": "Retrieve a profile", "description": "Returns user profile information.", "parameters": [ { "name": "include[]", "in": "query", "description": "A list of additional information you want to receive for the user. By default only personal and merchant profile information will be returned.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "settings", "doing_business_as", "bank_accounts", "app_settings", "country_details" ] } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantAccount" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "user.profile", "user.profile_readonly" ] } ], "tags": [ "Merchant" ], "x-codegen": { "method_name": "get" }, "x-scopes": [ "user.profile", "user.profile_readonly" ] } }, "/v1.0/merchants/{merchant_code}/payouts": { "get": { "operationId": "ListPayoutsV1", "summary": "List payouts", "description": "Lists ordered payouts for the merchant profile.", "parameters": [ { "name": "merchant_code", "in": "path", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "start_date", "in": "query", "description": "Start date (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "End date (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "desc", "asc" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialPayouts" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "user.profile", "user.profile_readonly" ] } ], "tags": [ "Payouts" ], "x-codegen": { "method_name": "list" }, "x-scopes": [ "user.profile", "user.profile_readonly" ] } }, "/v0.1/me/financials/payouts": { "get": { "operationId": "ListPayouts", "summary": "List payouts", "description": "Lists ordered payouts for the merchant profile.", "parameters": [ { "name": "start_date", "in": "query", "description": "Start date (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "End date (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "desc", "asc" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialPayouts" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } } }, "deprecated": true, "security": [ { "apiKey": [] }, { "oauth2": [ "user.profile", "user.profile_readonly" ] } ], "tags": [ "Payouts" ], "x-codegen": { "method_name": "list_deprecated" }, "x-scopes": [ "user.profile", "user.profile_readonly" ] } }, "/v0.1/me/personal-profile": { "get": { "operationId": "GetPersonalProfile", "summary": "Retrieve a personal profile", "description": "Retrieves personal profile data.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalProfile" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "user.profile", "user.profile_readonly" ] } ], "tags": [ "Merchant" ], "x-codegen": { "method_name": "get_personal_profile" }, "x-scopes": [ "user.profile", "user.profile_readonly" ] } }, "/v0.1/me/merchant-profile": { "get": { "operationId": "GetMerchantProfile", "summary": "Retrieve a merchant profile", "description": "Retrieves merchant profile data.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantProfile" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "user.profile", "user.profile_readonly" ] } ], "tags": [ "Merchant" ], "x-codegen": { "method_name": "get_merchant_profile" }, "x-scopes": [ "user.profile", "user.profile_readonly" ] } }, "/v0.1/me/merchant-profile/doing-business-as": { "get": { "operationId": "GetDoingBusinessAs", "summary": "Retrieve DBA", "description": "Retrieves Doing Business As profile.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DoingBusinessAs" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "user.profile", "user.profile_readonly" ] } ], "tags": [ "Merchant" ], "x-codegen": { "method_name": "get_doing_business_as" }, "x-scopes": [ "user.profile", "user.profile_readonly" ] } }, "/v1.1/merchants/{merchant_code}/bank-accounts": { "get": { "operationId": "ListBankAccountsV11", "summary": "List bank accounts", "description": "Retrieves bank accounts of the merchant.", "parameters": [ { "name": "merchant_code", "in": "path", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "primary", "in": "query", "description": "If true only the primary bank account (the one used for payouts) will be returned.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccount" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "user.payout-settings", "user.profile", "user.profile_readonly" ] } ], "tags": [ "Merchant" ], "x-codegen": { "method_name": "list_bank_accounts" }, "x-scopes": [ "user.payout-settings", "user.profile", "user.profile_readonly" ] } }, "/v0.1/me/merchant-profile/bank-accounts": { "get": { "operationId": "ListBankAccounts", "summary": "List bank accounts", "description": "Retrieves bank accounts of the merchant.", "parameters": [ { "name": "primary", "in": "query", "description": "If true only the primary bank account (the one used for payouts) will be returned.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccount" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } } }, "deprecated": true, "security": [ { "apiKey": [] }, { "oauth2": [ "user.payout-settings", "user.profile", "user.profile_readonly" ] } ], "tags": [ "Merchant" ], "x-codegen": { "method_name": "list_bank_accounts_deprecated" }, "x-scopes": [ "user.payout-settings", "user.profile", "user.profile_readonly" ] } }, "/v0.1/me/merchant-profile/settings": { "get": { "operationId": "GetSettings", "summary": "Get settings", "description": "Retrieves merchant settings.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantSettings" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "user.payout-settings" ] } ], "tags": [ "Merchant" ], "x-codegen": { "method_name": "get_settings" }, "x-scopes": [ "user.payout-settings" ] } }, "/v1.1/receipts/{id}": { "get": { "operationId": "GetReceipt", "summary": "Retrieve receipt details", "description": "Retrieves receipt specific data for a transaction.", "parameters": [ { "name": "id", "in": "path", "description": "SumUp unique transaction ID or transaction code, e.g. TS7HDYLSKD.", "required": true, "schema": { "type": "string" } }, { "name": "mid", "in": "query", "description": "Merchant code.", "required": true, "schema": { "type": "string" } }, { "name": "tx_event_id", "in": "query", "description": "The ID of the transaction event (refund).", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Receipts" ], "x-codegen": { "method_name": "get" }, "x-scopes": [] } }, "/v0.1/merchants/{merchant_code}/readers/{id}/checkout": { "post": { "operationId": "CreateReaderCheckout", "summary": "Create a Reader Checkout", "description": "Create a Checkout for a Reader.\n\nThis process is asynchronous and the actual transaction may take some time to be stared on the device.\n\n\nThere are some caveats when using this endpoint:\n* The target device must be online, otherwise checkout won't be accepted\n* After the checkout is accepted, the system has 60 seconds to start the payment on the target device. During this time, any other checkout for the same device will be rejected.\n\n**Note**: If the target device is a Solo, it must be in version 3.3.24.3 or higher.\n", "parameters": [ { "name": "merchant_code", "in": "path", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "id", "in": "path", "description": "The unique identifier of the reader.\n", "required": true, "schema": { "type": "string", "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "maxLength": 30, "minLength": 30 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReaderCheckout" } } } }, "responses": { "201": { "description": "The Checkout got successfully created for the given reader.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "client_transaction_id": { "description": "The client transaction ID is a unique identifier for the transaction that is generated for the client.\nIt can be used later to fetch the transaction details via the [Transactions API](https://developer.sumup.com/api/transactions/get).\n", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "detail": { "type": "string", "example": "Bad Request" } } } } } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "examples": { "ReaderOffline": { "description": "Error returned when the target device is not online.", "value": { "errors": { "detail": "The device is offline.", "type": "READER_OFFLINE" } } }, "ReaderCheckoutPending": { "description": "Error returned when a checkout was requested in the last 60 seconds.", "value": { "errors": { "detail": "A pending transaction already exists for this device" } } }, "DataValidation": { "description": "Validation errors for the informed fields.", "value": { "errors": { "total_amount": [ "is too low", "this merchant can only accept 'EUR'" ], "installments": [ "not allowed" ], "card_type": [ "is invalid" ] } } } }, "schema": { "type": "object", "properties": { "errors": { "type": "object", "additionalProperties": true } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "detail": { "type": "string", "example": "Internal Server Error" } } } } } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "detail": { "type": "string", "example": "Bad Gateway" } } } } } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "detail": { "type": "string", "example": "Gateway Timeout" } } } } } } } } }, "callbacks": { "ReaderCheckoutStatusChange": { "{$request.body#/return_url}": { "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReaderCheckoutStatusChange" } } } }, "responses": { "200": { "description": "Your server returns this code if it accepts the callback.\nIf the server returns any other code, the callback will be retried up to 5 times with exponential backoff.\n" } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.write" ] } ], "tags": [ "Readers" ], "x-codegen": { "method_name": "create_checkout" }, "x-permissions": [ "readers_checkout_create" ], "x-scopes": [ "readers.write" ] } }, "/v0.1/merchants/{merchant_code}/readers/{id}/terminate": { "post": { "operationId": "CreateReaderTerminate", "summary": "Create a Reader Terminate action", "description": "Create a Terminate action for a Reader.\n\nIt stops the current transaction on the target device.\n\nThis process is asynchronous and the actual termination may take some time to be performed on the device.\n\n\nThere are some caveats when using this endpoint:\n* The target device must be online, otherwise terminate won't be accepted\n* The action will succeed only if the device is waiting for cardholder action: e.g: waiting for card, waiting for PIN, etc.\n* There is no confirmation of the termination.\n\nIf a transaction is successfully terminated and `return_url` was provided on Checkout, the transaction status will be sent as `failed` to the provided URL.\n\n**Note**: If the target device is a Solo, it must be in version 3.3.28.0 or higher.\n", "parameters": [ { "name": "merchant_code", "in": "path", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "id", "in": "path", "description": "The unique identifier of the reader.\n", "required": true, "schema": { "type": "string", "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "maxLength": 30, "minLength": 30 } } ], "responses": { "202": { "description": "The Terminate action was successfully dispatched for the given reader.\n" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "examples": { "ReaderOffline": { "description": "Error returned when the target device is not online.", "value": { "errors": { "detail": "The device is offline.", "type": "READER_OFFLINE" } } } }, "schema": { "type": "object", "properties": { "errors": { "type": "object", "additionalProperties": true } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "detail": { "type": "string", "example": "Internal Server Error" } } } } } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "detail": { "type": "string", "example": "Bad Gateway" } } } } } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "detail": { "type": "string", "example": "Gateway Timeout" } } } } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.write" ] } ], "tags": [ "Readers" ], "x-codegen": { "method_name": "terminate_checkout" }, "x-permissions": [ "readers_checkout_create" ], "x-scopes": [ "readers.write" ] } }, "/v0.1/merchants/{merchant_code}/api-keys": { "get": { "operationId": "ListAPIKeys", "summary": "List API keys", "description": "List merchant's API keys.", "parameters": [ { "name": "offset", "in": "query", "description": "Offset of the first API Key to return.", "schema": { "type": "integer", "example": 0, "default": 0, "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Maximum number of API Keys to return.", "schema": { "type": "integer", "example": 10, "default": 10, "maximum": 25, "minimum": 1 } }, { "name": "merchant_code", "in": "path", "description": "Unique identifier of the merchant account.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } } ], "responses": { "200": { "description": "Returns a list of API Key objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeysList" } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "api_keys" ] } ], "tags": [ "API Keys" ], "x-codegen": { "method_name": "list" }, "x-permissions": [ { "relation": "api_keys_list", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "api_keys" ] }, "post": { "operationId": "CreateAPIKey", "summary": "Create an API key", "description": "Create a new API key.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Unique identifier of the merchant account.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Name of the API key.", "type": "string", "example": "New Key Name", "maxLength": 255 }, "scopes": { "$ref": "#/components/schemas/OAuth2Scopes" } }, "required": [ "name", "scopes" ] } } } }, "responses": { "201": { "description": "Returns the API Key object if the creation succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKey" } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "api_keys:write" ] } ], "tags": [ "API Keys" ], "x-codegen": { "method_name": "create" }, "x-permissions": [ { "relation": "api_keys_create", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "api_keys:write" ] } }, "/v0.1/merchants/{merchant_code}/api-keys/{key_id}": { "get": { "operationId": "GetAPIKey", "summary": "Retrieve an API Key", "description": "Retrieve an API key.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Unique identifier of the merchant account.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "key_id", "in": "path", "description": "The ID of the API Key to retrieve.", "required": true, "schema": { "type": "string", "example": "sup_pk_1tpmgSzNUHMkxZD1Kz2hdQorZAav6AcZ9" } } ], "responses": { "200": { "description": "Returns the API Key object for a valid identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKey" } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "api_keys" ] } ], "tags": [ "API Keys" ], "x-codegen": { "method_name": "get" }, "x-permissions": [ { "relation": "api_keys_view", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "api_keys" ] }, "put": { "operationId": "UpdateAPIKey", "summary": "Update an API key", "description": "Update an API key.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Unique identifier of the merchant account.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "key_id", "in": "path", "description": "The ID of the API Key to retrieve.", "required": true, "schema": { "type": "string", "example": "sup_pk_1tpmgSzNUHMkxZD1Kz2hdQorZAav6AcZ9" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "New name for the API key.", "type": "string", "example": "My API Key", "maxLength": 255 }, "scopes": { "$ref": "#/components/schemas/OAuth2Scopes" } }, "required": [ "name", "scopes" ] } } } }, "responses": { "204": { "description": "Returns an empty response if the update succeeded." } }, "security": [ { "apiKey": [] }, { "oauth2": [ "api_keys:write" ] } ], "tags": [ "API Keys" ], "x-codegen": { "method_name": "update" }, "x-permissions": [ { "relation": "api_keys_update", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "api_keys:write" ] }, "delete": { "operationId": "DeleteAPIKey", "summary": "Delete an API key", "description": "Delete an API key.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Unique identifier of the merchant account.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "key_id", "in": "path", "description": "The ID of the API Key to retrieve.", "required": true, "schema": { "type": "string", "example": "sup_pk_1tpmgSzNUHMkxZD1Kz2hdQorZAav6AcZ9" } } ], "responses": { "204": { "description": "Returns an empty response of the deletion succeeded." } }, "security": [ { "apiKey": [] }, { "oauth2": [ "api_keys:write" ] } ], "tags": [ "API Keys" ], "x-codegen": { "method_name": "delete" }, "x-permissions": [ { "relation": "api_keys_delete", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "api_keys:write" ] } }, "/v0.1/me/accounts": { "get": { "operationId": "ListSubAccounts", "summary": "List operators.", "description": "Returns list of operators for currently authorized user's merchant.", "parameters": [ { "name": "query", "in": "query", "description": "Search query used to filter users that match given query term.\n\nCurrent implementation allow querying only over the email address.\nAll operators whos email address contains the query string are returned.\n", "schema": { "type": "string" } }, { "name": "include_primary", "in": "query", "description": "If true the list of operators will include also the primary user.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of operators.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Operator" } } } } } }, "deprecated": true, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Subaccounts" ], "x-deprecation-notice": "Subaccounts API is deprecated, to list users in your merchant account please use [List members](https://developer.sumup.com/api/members/list) instead.", "x-permissions": [ "members_list" ], "x-scopes": [] }, "post": { "operationId": "CreateSubAccount", "summary": "Create operator.", "description": "Creates new operator for currently authorized users' merchant.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "format": "email", "example": "operator1@mydomain.com" }, "password": { "type": "string", "example": "correct horse batter staple", "minLength": 8 }, "nickname": { "type": "string", "example": "Operator 1" }, "permissions": { "type": "object", "properties": { "create_moto_payments": { "type": "boolean" }, "create_referral": { "type": "boolean" }, "full_transaction_history_view": { "type": "boolean" }, "refund_transactions": { "type": "boolean" } } } }, "required": [ "username", "password" ] } } } }, "responses": { "200": { "description": "Newly created operator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } }, "403": { "description": "error response for compat API calls", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatError" } } } } }, "deprecated": true, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Subaccounts" ], "x-deprecation-notice": "Subaccounts API is deprecated, to create an user in your merchant account please use [Create member](https://developer.sumup.com/api/members/create) instead.", "x-permissions": [ "members_update" ], "x-scopes": [] } }, "/v0.1/me/accounts/{operator_id}": { "get": { "operationId": "CompatGetOperator", "summary": "Get operator", "description": "Returns specific operator.", "parameters": [ { "name": "operator_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Operator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } }, "deprecated": true, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Subaccounts" ], "x-deprecation-notice": "Subaccounts API is deprecated, to get an user that's a member of your merchant account please use [Get member](https://developer.sumup.com/api/members/get) instead.", "x-permissions": [ "members_view" ], "x-scopes": [] }, "put": { "operationId": "UpdateSubAccount", "summary": "Update operator.", "description": "Updates operator. If the operator was disabled and their password is updated they will be unblocked.", "parameters": [ { "name": "operator_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "example": "correct horse batter staple", "minLength": 8 }, "username": { "type": "string", "format": "email", "maxLength": 256 }, "disabled": { "type": "boolean" }, "nickname": { "type": "string", "example": "Operator 1" }, "permissions": { "type": "object", "properties": { "create_moto_payments": { "type": "boolean" }, "create_referral": { "type": "boolean" }, "full_transaction_history_view": { "type": "boolean" }, "refund_transactions": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "Updated operator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } }, "400": { "description": "Invalid Operators' email or password was already used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatError" } } } } }, "deprecated": true, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Subaccounts" ], "x-deprecation-notice": "Subaccounts API is deprecated, to update an user that's a member of your merchant account please use [Update member](https://developer.sumup.com/api/members/update) instead.", "x-permissions": [ "members_update" ], "x-scopes": [] }, "delete": { "operationId": "DeactivateSubAccount", "summary": "Disable operator.", "parameters": [ { "name": "operator_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Operator successfully disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } }, "deprecated": true, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Subaccounts" ], "x-deprecation-notice": "Subaccounts API is deprecated, to remove an user that's a member of your merchant account please use [Delete member](https://developer.sumup.com/api/members/delete) instead.", "x-permissions": [ "members_delete" ], "x-scopes": [] } }, "/v0.1/memberships": { "get": { "operationId": "ListMemberships", "summary": "List memberships", "description": "List memberships of the current user.", "parameters": [ { "name": "offset", "in": "query", "description": "Offset of the first member to return.", "schema": { "type": "integer", "example": 0, "default": 0, "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Maximum number of members to return.", "schema": { "type": "integer", "example": 10, "default": 10, "maximum": 25, "minimum": 1 } }, { "name": "kind", "in": "query", "description": "Filter memberships by resource kind.", "schema": { "description": "The kind of the membership resource.\nPossible values are:\n* `merchant` - merchant account(s)", "type": "string", "enum": [ "merchant" ] } }, { "name": "resource.attributes.sandbox", "in": "query", "description": "Filter memberships by the sandbox status of the resource the membership is in.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Returns a list of Membership objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Membership" } }, "total_count": { "type": "integer", "example": 3 } }, "required": [ "total_count", "items" ] } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Memberships" ], "x-codegen": { "method_name": "list" }, "x-scopes": [] } }, "/v0.1/merchants/{merchant_code}/members": { "get": { "operationId": "ListMerchantMembers", "summary": "List members", "description": "Lists merchant members.", "parameters": [ { "name": "offset", "in": "query", "description": "Offset of the first member to return.", "schema": { "type": "integer", "example": 0, "default": 0, "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Maximum number of members to return.", "schema": { "type": "integer", "example": 10, "default": 10, "maximum": 25, "minimum": 1 } }, { "name": "scroll", "in": "query", "description": "Indicates to skip count query.", "schema": { "type": "boolean", "example": true, "default": false } }, { "name": "email", "in": "query", "description": "Filter the returned members by email address prefix.", "schema": { "type": "string", "example": "user" } }, { "name": "status", "in": "query", "description": "Filter the returned members by the membership status.", "schema": { "$ref": "#/components/schemas/MembershipStatus" } }, { "name": "roles", "in": "query", "description": "Filter the returned members by role.", "schema": { "type": "array", "items": { "type": "string" }, "example": [ "role_employee", "role_accountant" ] }, "explode": true, "style": "form" }, { "name": "merchant_code", "in": "path", "description": "Merchant code.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } } ], "responses": { "200": { "description": "Returns a list of Member objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "total_count": { "type": "integer", "example": 3 } }, "required": [ "items" ] } } } }, "404": { "description": "Merchant not found." } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Members" ], "x-codegen": { "method_name": "list" }, "x-permissions": [ { "relation": "merchant_read", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [] }, "post": { "operationId": "CreateMerchantMember", "summary": "Create a member", "description": "Create a merchant member.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Merchant code.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_managed_user": { "description": "True if the user is managed by the merchant. In this case, we'll created a virtual user with the provided password and nickname.", "type": "boolean" }, "is_service_account": { "description": "True if the user is a service account. It can later be used to create OAuth2 clients.", "type": "boolean" }, "email": { "description": "Email address of the member to add.", "type": "string", "format": "email" }, "password": { "description": "Password of the member to add. Only used if `is_managed_user` is true. In the case of service accounts, the password is not used and can not be defined by the caller.", "type": "string", "format": "password", "minLength": 8 }, "nickname": { "description": "Nickname of the member to add. Only used if `is_managed_user` is true. Used for display purposes only.", "type": "string", "example": "Test User" }, "roles": { "description": "List of roles to assign to the new member. In the case of service accounts, the roles are predefined.", "type": "array", "items": { "type": "string" } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "attributes": { "$ref": "#/components/schemas/Attributes" } }, "required": [ "email", "roles" ] } } } }, "responses": { "201": { "description": "Returns the Member object if the creation succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "description": "Invalid request." }, "404": { "description": "Merchant not found." }, "429": { "description": "Too many invitations sent to that user. The limit is 10 requests per 5 minutes and the Retry-After header is set to the number of minutes until the reset of the limit." } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Members" ], "x-codegen": { "method_name": "create" }, "x-permissions": [ { "relation": "members_create", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [] } }, "/v0.1/merchants/{merchant_code}/members/{member_id}": { "get": { "operationId": "GetMerchantMember", "summary": "Retrieve a member", "description": "Retrieve a merchant member.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Merchant code.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "member_id", "in": "path", "description": "The ID of the member to retrieve.", "required": true, "schema": { "type": "string", "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" } } ], "responses": { "200": { "description": "Returns the Member object for a valid identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "404": { "description": "Merchant or member not found." } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Members" ], "x-codegen": { "method_name": "get" }, "x-permissions": [ { "relation": "members_view", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [] }, "put": { "operationId": "UpdateMerchantMember", "summary": "Update a member", "description": "Update the merchant member.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Merchant code.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "member_id", "in": "path", "description": "The ID of the member to retrieve.", "required": true, "schema": { "type": "string", "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "string" } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "attributes": { "$ref": "#/components/schemas/Attributes" }, "user": { "description": "Allows you to update user data of managed users.", "type": "object", "properties": { "nickname": { "description": "User's preferred name. Used for display purposes only.", "type": "string", "example": "Test User" }, "password": { "description": "Password of the member to add. Only used if `is_managed_user` is true.", "type": "string", "format": "password", "minLength": 8 } } } } } } } }, "responses": { "200": { "description": "Returns the updated Member object if the update succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "description": "Cannot set password or nickname for an invited user." }, "403": { "description": "Cannot change password for managed user. Password was already used before." }, "404": { "description": "Merchant or member not found." }, "409": { "description": "Cannot update member as some data conflict with existing members." } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Members" ], "x-codegen": { "method_name": "update" }, "x-permissions": [ { "relation": "members_update", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [] }, "delete": { "operationId": "DeleteMerchantMember", "summary": "Delete a member", "description": "Deletes a merchant member.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Merchant code.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "member_id", "in": "path", "description": "The ID of the member to retrieve.", "required": true, "schema": { "type": "string", "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" } } ], "responses": { "200": { "description": "Returns an empty response if the deletion succeeded." }, "404": { "description": "Merchant or member not found." } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Members" ], "x-codegen": { "method_name": "delete" }, "x-permissions": [ { "relation": "members_delete", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [] } }, "/v0.1/merchants/{merchant_code}/roles": { "get": { "operationId": "ListMerchantRoles", "summary": "List roles", "description": "List merchant's custom roles.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Merchant code.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } } ], "responses": { "200": { "description": "Returns a list of Role objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } }, "required": [ "items" ] } } } }, "404": { "description": "Merchant not found." } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Roles" ], "x-codegen": { "method_name": "list" }, "x-permissions": [ { "relation": "roles_list", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [] }, "post": { "operationId": "CreateMerchantRole", "summary": "Create a role", "description": "Create a custom role for the merchant. Roles are defined by the set of permissions that they grant to the members that they are assigned to.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Merchant code.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "User-defined name of the role.", "type": "string", "example": "Senior Shop Manager II" }, "permissions": { "description": "User's permissions.", "type": "array", "items": { "type": "string" }, "example": [ "members_list", "members_read", "members_view", "members_write", "members_delete" ], "maxItems": 100 }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "description": { "description": "User-defined description of the role.", "type": "string", "example": "Manges the shop and the employees." } }, "required": [ "name", "permissions" ] } } } }, "responses": { "201": { "description": "Returns the Role object after successful custom role creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "400": { "description": "Invalid request." }, "404": { "description": "Merchant not found." } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Roles" ], "x-codegen": { "method_name": "create" }, "x-permissions": [ { "relation": "roles_create", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [] } }, "/v0.1/merchants/{merchant_code}/roles/{role_id}": { "get": { "operationId": "GetMerchantRole", "summary": "Retrieve a role", "description": "Retrieve a custom role by ID.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Merchant code.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "role_id", "in": "path", "description": "The ID of the role to retrieve.", "required": true, "schema": { "type": "string", "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", "x-go-type": "memberships.RoleID", "x-go-type-import": { "path": "github.com/sumup/identity/apps/portier-backend/internal/domain/memberships" } } } ], "responses": { "200": { "description": "Returns the Role object for a valid identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "404": { "description": "Merchant or role not found." } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Roles" ], "x-codegen": { "method_name": "get" }, "x-permissions": [ { "relation": "roles_view", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [] }, "delete": { "operationId": "DeleteMerchantRole", "summary": "Delete a role", "description": "Delete a custom role.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Merchant code.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "role_id", "in": "path", "description": "The ID of the role to retrieve.", "required": true, "schema": { "type": "string", "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", "x-go-type": "memberships.RoleID", "x-go-type-import": { "path": "github.com/sumup/identity/apps/portier-backend/internal/domain/memberships" } } } ], "responses": { "200": { "description": "Returns the deleted Role object if the deletion succeeded." }, "400": { "description": "Invalid request." }, "404": { "description": "Merchant not found." } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Roles" ], "x-codegen": { "method_name": "delete" }, "x-permissions": [ { "relation": "roles_delete", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [] }, "patch": { "operationId": "UpdateMerchantRole", "summary": "Update a role", "description": "Update a custom role.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Merchant code.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "role_id", "in": "path", "description": "The ID of the role to retrieve.", "required": true, "schema": { "type": "string", "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", "x-go-type": "memberships.RoleID", "x-go-type-import": { "path": "github.com/sumup/identity/apps/portier-backend/internal/domain/memberships" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "User-defined name of the role.", "type": "string", "example": "Senior Shop Manager II" }, "permissions": { "description": "User's permissions.", "type": "array", "items": { "type": "string" }, "example": [ "members_list", "members_read", "members_view", "members_write", "members_delete" ], "maxItems": 100 }, "description": { "description": "User-defined description of the role.", "type": "string", "example": "Manges the shop and the employees." } } } } } }, "responses": { "200": { "description": "Returns the updated Role object if the update succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "400": { "description": "Invalid request." }, "404": { "description": "Merchant not found." } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ "Roles" ], "x-codegen": { "method_name": "update" }, "x-permissions": [ { "relation": "roles_update", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [] } }, "/v0.1/merchants/{merchant_code}/readers": { "get": { "operationId": "ListReaders", "summary": "List Readers", "description": "List all readers of the merchant.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Unique identifier of the merchant account.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } } ], "responses": { "200": { "description": "Returns a list Reader objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Reader" } } }, "required": [ "items" ] } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.read" ] } ], "tags": [ "Readers" ], "x-codegen": { "method_name": "list" }, "x-permissions": [ { "relation": "readers_list", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "readers.read" ] }, "post": { "operationId": "CreateReader", "summary": "Create a Reader", "description": "Create a new Reader for the merchant account.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Unique identifier of the merchant account.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pairing_code": { "$ref": "#/components/schemas/ReaderPairingCode" }, "name": { "$ref": "#/components/schemas/ReaderName" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "pairing_code" ] } } } }, "responses": { "201": { "description": "Returns the Reader object if the creation succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reader" }, "examples": { "created": { "summary": "A reader that waits for the physical device to acknowledge the pairing.", "value": { "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "name": "Frontdesk", "status": "processing", "device": { "identifier": "U1DT3NA00-CN", "model": "solo" }, "created_at": "2023-05-09T14:50:20.214Z", "updated_at": "2023-05-09T14:52:58.714Z" } } } } }, "links": { "UpdateReaderByID": { "operationId": "UpdateReader", "parameters": { "id": "$response.body#/id" }, "description": "Update the reader object. This can be used to set a name after using this endpoint to verify the pairing code.\n" }, "DeleteReaderByID": { "operationId": "DeleteReader", "parameters": { "id": "$response.body#/id" }, "description": "Delete the reader.\n" } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.write" ] } ], "tags": [ "Readers" ], "x-codegen": { "method_name": "create" }, "x-permissions": [ { "relation": "readers_create", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "readers.write" ] } }, "/v0.1/merchants/{merchant_code}/readers/{id}": { "get": { "operationId": "GetReader", "summary": "Retrieve a Reader", "description": "Retrieve a Reader.", "parameters": [ { "name": "If-Modified-Since", "in": "header", "description": "Return the reader only if it has been modified after the specified timestamp given in the headers.\nTimestamps are accepted in the following formats:\n\n\n - HTTP Standard: [IMF format (RFC 5322)](https://www.rfc-editor.org/rfc/rfc5322#section-3.3), sometimes also referred to as [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231#section-7.1.1.1).\n - RFC 3339: Used for timestamps in JSON payloads on this API.", "required": false, "schema": { "type": "string", "oneOf": [ { "format": "httpdate", "type": "string", "example": "Tue, 03 May 2022 14:46:44 GMT" }, { "format": "date-time", "type": "string", "example": "2023-05-30T10:38:01+00:00" } ] } }, { "name": "merchant_code", "in": "path", "description": "Unique identifier of the merchant account.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "id", "in": "path", "description": "The unique identifier of the reader.", "required": true, "schema": { "$ref": "#/components/schemas/ReaderID" } } ], "responses": { "200": { "description": "Returns a Reader object for a valid identifier.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reader" } } } }, "400": { "description": "Malformed request." }, "404": { "description": "The requested Reader resource does not exists.\n" } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.read" ] } ], "tags": [ "Readers" ], "x-codegen": { "method_name": "get" }, "x-permissions": [ { "relation": "readers_view", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "readers.read" ] }, "delete": { "operationId": "DeleteReader", "summary": "Delete a reader", "description": "Delete a reader.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Unique identifier of the merchant account.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "id", "in": "path", "description": "The unique identifier of the reader.", "required": true, "schema": { "$ref": "#/components/schemas/ReaderID" } } ], "responses": { "200": { "description": "Returns an empty response if the deletion succeeded." } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.write" ] } ], "tags": [ "Readers" ], "x-permissions": [ { "relation": "readers_delete", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "readers.write" ] }, "patch": { "operationId": "UpdateReader", "summary": "Update a Reader", "description": "Update a Reader.", "parameters": [ { "name": "merchant_code", "in": "path", "description": "Unique identifier of the merchant account.", "required": true, "schema": { "type": "string", "example": "MC0X0ABC" } }, { "name": "id", "in": "path", "description": "The unique identifier of the reader.", "required": true, "schema": { "$ref": "#/components/schemas/ReaderID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/ReaderName" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "responses": { "304": { "description": "The update request was successful, but the reader didn't get updated." }, "403": { "description": "The reader is not linked to the merchant account." } }, "security": [ { "apiKey": [] }, { "oauth2": [ "readers.write" ] } ], "tags": [ "Readers" ], "x-codegen": { "method_name": "update" }, "x-permissions": [ { "relation": "readers_update", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "readers.write" ] } } }, "components": { "parameters": { "ChangesSinceFilter": { "name": "changes_since", "in": "query", "description": "Filters the results by the latest modification time of resources and returns only transactions that are modified *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, "CheckoutID": { "name": "id", "in": "path", "required": true, "description": "Unique ID of the checkout resource.", "schema": { "type": "string" } }, "CheckoutReference": { "name": "checkout_reference", "in": "query", "description": "Filters the list of checkout resources by the unique ID of the checkout.", "required": false, "schema": { "type": "string" } }, "CustomerID": { "name": "customer_id", "in": "path", "required": true, "description": "Unique ID of the saved customer resource.", "schema": { "type": "string" } }, "GeoCoordinatesFilter": { "name": "geo_coordinates", "in": "query", "description": "Filters the results by the geographical coordinates of the location where the transaction is made (as retrieved from the terminal device) and returns only results that fall within the specified rectangular area. The accepted format is a comma-separated list of coordinate points that form a rectangle defined by the following parameters:\n\n * `southwest_lng` (for the longitude value of the southwestern edge of the rectangle)\n * `southwest_lat` (for the latitude value of the southwestern edge of the rectangle)\n * `northeast_lng` (for the longitude value of the northeastern edge of the rectangle)\n * `northeast_lat` (for the latitude value of the northeastern edge of the rectangle)\n", "required": false, "schema": { "type": "string" } }, "LimitFilter": { "name": "limit", "in": "query", "description": "Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results.", "schema": { "type": "integer" } }, "NewestRefFilter": { "name": "newest_ref", "in": "query", "description": "Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *smaller* than the specified value. This parameters supersedes the `newest_time` parameter (if both are provided in the request).", "required": false, "schema": { "type": "string" } }, "NewestTimeFilter": { "name": "newest_time", "in": "query", "description": "Filters the results by the creation time of resources and returns only transactions that are created *before* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, "OrderFilter": { "name": "order", "in": "query", "description": "Specifies the order in which the returned results are displayed.", "schema": { "type": "string", "default": "ascending", "enum": [ "ascending", "descending" ] } }, "PaymentTypesFilter": { "name": "payment_types", "in": "query", "description": "Filters the returned results by the specified list of payment types used for the transactions.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "CASH", "POS", "ECOM", "BALANCE", "MOTO", "BOLETO", "UNKNOWN" ] } } }, "ReadersFilter": { "name": "readers", "in": "query", "description": "Filters the returned results by the specified list of serial numbers of the terminal readers used for the transactions.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, "StatusesFilter": { "name": "statuses", "in": "query", "description": "Filters the returned results by the specified list of final statuses of the transactions.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "SUCCESSFUL", "CANCELLED", "FAILED", "REFUNDED", "CHARGE_BACK" ] } } }, "Token": { "name": "token", "in": "path", "required": true, "description": "Unique token identifying the card saved as a payment instrument resource.", "schema": { "type": "string" } }, "TransactionCode": { "name": "transaction_code", "in": "query", "description": "Retrieves the transaction resource with the specified transaction code.", "required": false, "schema": { "type": "string" } }, "TransactionID": { "name": "id", "in": "query", "description": "Retrieves the transaction resource with the specified transaction ID (the `id` parameter in the transaction resource).", "required": false, "schema": { "type": "string" } }, "TxnID": { "in": "path", "name": "txn_id", "required": true, "description": "Unique ID of the transaction.", "schema": { "type": "string" } }, "TypesFilter": { "name": "types", "in": "query", "description": "Filters the returned results by the specified list of transaction types.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "PAYMENT", "REFUND", "CHARGE_BACK" ] } } }, "UsersFilter": { "name": "users", "in": "query", "description": "Filters the returned results by user email.", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "email" } } } }, "schemas": { "Account": { "description": "Profile information.", "type": "object", "properties": { "username": { "description": "Username of the user profile.", "type": "string" }, "type": { "description": "The role of the user.", "type": "string", "enum": [ "normal", "operator" ] } } }, "Address": { "description": "Profile's personal address information.", "type": "object", "properties": { "city": { "description": "City name from the address.", "type": "string", "example": "Berlin" }, "country": { "description": "Two letter country code formatted according to [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "example": "DE" }, "line1": { "description": "First line of the address with details of the street name and number.", "type": "string", "example": "Sample street" }, "line2": { "description": "Second line of the address with details of the building, unit, apartment, and floor numbers.", "type": "string", "example": "ap. 5" }, "postal_code": { "description": "Postal code from the address.", "type": "string", "example": "10115" }, "state": { "description": "State name or abbreviation from the address.", "type": "string", "example": "Berlin" } }, "required": [ "country" ] }, "AddressWithDetails": { "description": "Details of the registered address.", "type": "object", "properties": { "address_line1": { "description": "Address line 1", "type": "string" }, "address_line2": { "description": "Address line 2", "type": "string" }, "city": { "description": "City", "type": "string" }, "country": { "description": "Country ISO 3166-1 code", "type": "string" }, "region_id": { "description": "Country region id", "type": "number" }, "region_name": { "description": "Region name", "type": "string" }, "region_code": { "description": "Region code", "type": "string" }, "post_code": { "description": "Postal code", "type": "string" }, "landline": { "description": "Landline number", "type": "string" }, "first_name": { "description": "undefined", "type": "string" }, "last_name": { "description": "undefined", "type": "string" }, "company": { "description": "undefined", "type": "string" }, "country_details": { "$ref": "#/components/schemas/CountryDetails" }, "timeoffset_details": { "$ref": "#/components/schemas/TimeoffsetDetails" }, "state_id": { "description": "undefined", "type": "string" } } }, "AddressPayload": { "description": "Personal address", "type": "object", "properties": { "address_line1": { "description": "Address line 1", "type": "string" }, "address_line2": { "description": "Address line 2", "type": "string" }, "city": { "description": "City", "type": "string" }, "country": { "description": "Country ISO 3166-1 code", "type": "string" }, "region_id": { "description": "Country region id", "type": "number" }, "region_name": { "description": "Country region name", "type": "string" }, "post_code": { "description": "Postal code", "type": "string" }, "landline": { "description": "Landline number", "type": "string" }, "first_name": { "description": "First name", "type": "string" }, "last_name": { "description": "Last name", "type": "string" }, "company": { "description": "Company name", "type": "string" } }, "required": [ "address_line1", "city", "country", "post_code" ] }, "Affiliate": { "description": "Affiliate metadata for the transaction.\nIt is an optional field that allow for integrators to track the source of the transaction.\n", "type": "object", "properties": { "app_id": { "description": "Application ID of the affiliate.\nIt is a unique identifier for the application and should be set by the integrator in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page.\n", "type": "string", "example": "com.example.app" }, "key": { "description": "Key of the affiliate.\nIt is a unique identifier for the key and should be generated by the integrator in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page.\n", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "foreign_transaction_id": { "description": "Foreign transaction ID of the affiliate.\nIt is a unique identifier for the transaction.\nIt can be used later to fetch the transaction details via the [Transactions API](https://developer.sumup.com/api/transactions/get).\n", "type": "string", "example": "123456" }, "tags": { "description": "Additional metadata for the transaction.\nIt is key-value object that can be associated with the transaction.\n", "type": "object", "example": {}, "additionalProperties": true } }, "required": [ "app_id", "key", "foreign_transaction_id" ] }, "AppSettings": { "description": "Mobile app settings", "type": "object", "properties": { "checkout_preference": { "description": "Checkout preference", "type": "string" }, "include_vat": { "description": "Include vat.", "type": "boolean" }, "manual_entry_tutorial": { "description": "Manual entry tutorial.", "type": "boolean" }, "mobile_payment_tutorial": { "description": "Mobile payment tutorial.", "type": "boolean" }, "tax_enabled": { "description": "Tax enabled.", "type": "boolean" }, "mobile_payment": { "description": "Mobile payment.", "type": "string" }, "reader_payment": { "description": "Reader payment.", "type": "string" }, "cash_payment": { "description": "Cash payment.", "type": "string" }, "advanced_mode": { "description": "Advanced mode.", "type": "string" }, "expected_max_transaction_amount": { "description": "Expected max transaction amount.", "type": "number" }, "manual_entry": { "description": "Manual entry.", "type": "string" }, "terminal_mode_tutorial": { "description": "Terminal mode tutorial.", "type": "boolean" }, "tipping": { "description": "Tipping.", "type": "string" }, "tip_rates": { "description": "Tip rates.", "type": "array", "items": { "type": "number", "format": "float" } }, "barcode_scanner": { "description": "Barcode scanner.", "type": "string" }, "referral": { "description": "Referral.", "type": "string" } } }, "AuthCode": { "description": "Authorization code flow", "type": "object", "properties": { "response_type": { "description": "The type of the expected response. The value must be `code` to indicate that you expect to receive an authorization code.", "type": "string", "example": "code" }, "client_id": { "description": "The client ID of your application that was generated when you [registered it](https://developer.sumup.com/docs/register-app/).", "type": "string", "example": "fOcmczrYtYMJ7Li5GjMLLcUeC9dN" }, "redirect_uri": { "description": "The URI to which the merchant user is redirected after authorizing your application to access their user's profile data and to which the authorization code is sent. The value must match exactly one of the [registered URIs](https://developer.sumup.com/docs/register-app#3-create-oauth-client-credentials) for your application.", "type": "string", "example": "https://sample-app.example.com/callback" }, "scope": { "description": "A space-separated list of scopes for which you request authorization. If you don't specify any scopes in the request, your application will be granted authorization for the default scopes.", "type": "string", "example": "payments" }, "state": { "description": "A unique local state that can be used for correlating requests and responses and for preventing [cross-site request forgery](https://tools.ietf.org/html/rfc6749#section-10.12).", "type": "string", "example": "2cFCsY36y95lFHk4" } }, "required": [ "response_type", "client_id", "redirect_uri" ] }, "AuthToken": { "description": "Authorization token flow", "type": "object", "properties": { "grant_type": { "description": "The grant type used for obtaining an access token.", "type": "string", "example": "refresh_token", "enum": [ "authorization_code", "refresh_token" ] }, "client_id": { "description": "The client ID of your application that was generated when you [registered it](https://developer.sumup.com/docs/register-app).", "type": "string", "example": "fOcmczrYtYMJ7Li5GjMLLcUeC9dN" }, "client_secret": { "description": "The client secret of your application that was generated when you [registered it](https://developer.sumup.com/docs/register-app).", "type": "string", "example": "717bd571b54297494cd7a79b491e8f2c1da6189c4cc2d3481380e8366eef539c" }, "code": { "description": "The authorization code that you received from requesting an authorization code.", "type": "string", "example": "be366ce9fccd0c337d1da29b31d06dd1135ab95401562883" }, "refresh_token": { "description": "A **required** parameter when generating a refresh token.", "type": "string", "example": "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af" } }, "required": [ "grant_type", "client_id", "client_secret", "code" ] }, "BankAccount": { "type": "object", "properties": { "bank_code": { "description": "Bank code", "type": "string" }, "branch_code": { "description": "Branch code", "type": "string" }, "swift": { "description": "SWIFT code", "type": "string" }, "account_number": { "description": "Account number", "type": "string" }, "iban": { "description": "IBAN", "type": "string" }, "account_type": { "description": "Type of the account", "type": "string" }, "account_category": { "description": "Account category - business or personal", "type": "string" }, "account_holder_name": { "type": "string" }, "status": { "description": "Status in the verification process", "type": "string" }, "primary": { "description": "The primary bank account is the one used for payouts", "type": "boolean" }, "created_at": { "description": "Creation date of the bank account", "type": "string" }, "bank_name": { "description": "Bank name", "type": "string" } } }, "BankAccountPayload": { "type": "object", "properties": { "bank_code": { "description": "Bank code", "type": "string" }, "branch_code": { "description": "Branch code", "type": "string" }, "account_number": { "description": "Account number", "type": "string" }, "iban": { "description": "IBAN", "type": "string" }, "swift": { "description": "SWIFT code", "type": "string" }, "account_type": { "description": "Type of the account.", "type": "string", "enum": [ "CURRENT", "SAVINGS" ] }, "account_holder_name": { "description": "Account holder name", "type": "string" }, "check_digit": { "description": "Check digit", "type": "string" }, "primary": { "description": "Determines if this bank account will be primary. Default is false", "type": "boolean" }, "status": { "description": "Determines the bank account status.", "type": "string", "enum": [ "OPEN" ] }, "account_category": { "description": "Determines if this bank account is business or personal.", "type": "string", "enum": [ "PERSONAL", "BUSINESS" ] } }, "required": [ "account_holder_name", "iban", "swift" ] }, "BusinessOwners": { "description": "Business owners information.", "type": "array", "items": { "type": "object", "properties": { "first_name": { "description": "BO's first name", "type": "string" }, "last_name": { "description": "BO's last name of the user", "type": "string" }, "date_of_birth": { "description": "Date of birth", "type": "string" }, "mobile_phone": { "description": "Mobile phone number", "type": "string" }, "landline": { "description": "BO's Landline", "type": "string" }, "ownership": { "description": "Ownership percentage", "type": "number" } } } }, "Card": { "description": "__Required when payment type is `card`.__ Details of the payment card.", "type": "object", "properties": { "name": { "description": "Name of the cardholder as it appears on the payment card.", "type": "string", "example": "FIRSTNAME LASTNAME", "writeOnly": true }, "number": { "description": "Number of the payment card (without spaces).", "type": "string", "example": "1234567890123456", "writeOnly": true }, "expiry_year": { "description": "Year from the expiration time of the payment card. Accepted formats are `YY` and `YYYY`.", "type": "string", "example": "2023", "maxLength": 4, "minLength": 2, "writeOnly": true }, "expiry_month": { "description": "Month from the expiration time of the payment card. Accepted format is `MM`.", "type": "string", "enum": [ "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12" ], "writeOnly": true }, "cvv": { "description": "Three or four-digit card verification value (security code) of the payment card.", "type": "string", "example": "123", "maxLength": 4, "minLength": 3, "writeOnly": true }, "zip_code": { "description": "Required five-digit ZIP code. Applicable only to merchant users in the USA.", "type": "string", "example": "12345", "maxLength": 5, "minLength": 5, "writeOnly": true }, "last_4_digits": { "description": "Last 4 digits of the payment card number.", "type": "string", "example": "3456", "maxLength": 4, "minLength": 4, "readOnly": true }, "type": { "description": "Issuing card network of the payment card.", "type": "string", "enum": [ "AMEX", "CUP", "DINERS", "DISCOVER", "ELO", "ELV", "HIPERCARD", "JCB", "MAESTRO", "MASTERCARD", "VISA", "VISA_ELECTRON", "VISA_VPAY", "UNKNOWN" ], "readOnly": true } }, "required": [ "name", "number", "expiry_month", "expiry_year", "cvv", "last_4_digits", "type" ] }, "CardResponse": { "description": "Details of the payment card.", "type": "object", "properties": { "last_4_digits": { "description": "Last 4 digits of the payment card number.", "type": "string", "example": "3456", "maxLength": 4, "minLength": 4, "readOnly": true }, "type": { "description": "Issuing card network of the payment card.", "type": "string", "enum": [ "AMEX", "CUP", "DINERS", "DISCOVER", "ELO", "ELV", "HIPERCARD", "JCB", "MAESTRO", "MASTERCARD", "VISA", "VISA_ELECTRON", "VISA_VPAY", "UNKNOWN" ], "readOnly": true } } }, "Checkout": { "description": "Details of the payment checkout.", "type": "object", "properties": { "checkout_reference": { "description": "Unique ID of the payment checkout specified by the client application when creating the checkout resource.", "type": "string", "maxLength": 90 }, "amount": { "description": "Amount of the payment.", "type": "number", "format": "float", "example": 10.1 }, "currency": { "$ref": "#/components/schemas/Currency" }, "pay_to_email": { "description": "Email address of the registered user (merchant) to whom the payment is made.", "type": "string", "format": "email" }, "merchant_code": { "description": "Unique identifying code of the merchant profile.", "type": "string" }, "description": { "description": "Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.", "type": "string" }, "return_url": { "description": "URL to which the SumUp platform sends the processing status of the payment checkout.", "type": "string", "format": "uri" }, "id": { "description": "Unique ID of the checkout resource.", "type": "string", "example": "4e425463-3e1b-431d-83fa-1e51c2925e99", "readOnly": true }, "status": { "description": "Current status of the checkout.", "type": "string", "enum": [ "PENDING", "FAILED", "PAID" ] }, "date": { "description": "Date and time of the creation of the payment checkout. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.", "type": "string", "format": "date-time", "example": "2020-02-29T10:56:56+00:00" }, "valid_until": { "description": "Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.", "type": "string", "format": "date-time", "example": "2020-02-29T10:56:56+00:00", "nullable": true }, "customer_id": { "description": "Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.", "type": "string", "example": "831ff8d4cd5958ab5670" }, "mandate": { "$ref": "#/components/schemas/MandateResponse" }, "transactions": { "description": "List of transactions related to the payment.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/TransactionMixinBase" }, { "$ref": "#/components/schemas/TransactionMixinCheckout" } ] }, "uniqueItems": true } }, "title": "Checkout" }, "CheckoutCreateRequest": { "description": "Details of the payment checkout.", "type": "object", "properties": { "checkout_reference": { "description": "Unique ID of the payment checkout specified by the client application when creating the checkout resource.", "type": "string", "maxLength": 90 }, "amount": { "description": "Amount of the payment.", "type": "number", "format": "float" }, "currency": { "$ref": "#/components/schemas/Currency" }, "merchant_code": { "description": "Unique identifying code of the merchant profile.", "type": "string" }, "pay_to_email": { "description": "Email address of the registered user (merchant) to whom the payment is made.", "type": "string", "format": "email", "deprecated": true, "x-deprecation-notice": "`pay_to_email` is deprecated, use `merchant_code` instead." }, "description": { "description": "Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.", "type": "string" }, "return_url": { "description": "URL to which the SumUp platform sends the processing status of the payment checkout.", "type": "string", "format": "uri" }, "customer_id": { "description": "Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.", "type": "string" }, "purpose": { "description": "Purpose of the checkout.", "type": "string", "default": "CHECKOUT", "enum": [ "CHECKOUT", "SETUP_RECURRING_PAYMENT" ] }, "id": { "description": "Unique ID of the checkout resource.", "type": "string", "readOnly": true }, "status": { "description": "Current status of the checkout.", "type": "string", "enum": [ "PENDING", "FAILED", "PAID" ], "readOnly": true }, "date": { "description": "Date and time of the creation of the payment checkout. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.", "type": "string", "format": "date-time", "example": "2020-02-29T10:56:56+00:00", "readOnly": true }, "valid_until": { "description": "Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.", "type": "string", "format": "date-time", "example": "2020-02-29T10:56:56+00:00", "nullable": true, "readOnly": true }, "transactions": { "description": "List of transactions related to the payment.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/TransactionMixinBase" }, { "$ref": "#/components/schemas/TransactionMixinCheckout" } ] }, "readOnly": true, "uniqueItems": true }, "redirect_url": { "description": "__Required__ for [APMs](https://developer.sumup.com/online-payments/apm/introduction) and __recommended__ for card payments. Refers to a url where the end user is redirected once the payment processing completes. If not specified, the [Payment Widget](https://developer.sumup.com/online-payments/tools/card-widget) renders [3DS challenge](https://developer.sumup.com/online-payments/features/3ds) within an iframe instead of performing a full-page redirect.", "type": "string", "example": "https://mysite.com/completed_purchase" }, "payment_type": { "description": "Alternative payment method name", "type": "string", "example": "boleto" }, "personal_details": { "description": "Object containing personal details about the payer, typical for __Boleto__ checkouts", "type": "object", "properties": { "email": { "description": "Payer's email address", "type": "string", "example": "test@example.com" }, "first_name": { "description": "Payer's first name", "type": "string", "example": "John" }, "last_name": { "description": "Payer's last name", "type": "string", "example": "Doe" }, "tax_id": { "description": "Payer's tax identification number (CPF)", "type": "string", "example": "423.378.593-47" }, "address": { "description": "Payer's address information", "type": "object", "properties": { "country": { "description": "Payer's country", "type": "string", "example": "BR" }, "city": { "description": "Payer's city", "type": "string", "example": "Rio de Janeiro" }, "line_1": { "description": "Field for address details", "type": "string" }, "state": { "description": "Payer's state code", "type": "string", "example": "RJ", "enum": [ "AC", "AL", "AP", "AM", "BA", "CE", "DF", "ES", "GO", "MA", "MT", "MS", "MG", "PA", "PB", "PR", "PE", "PI", "RJ", "RN", "RS", "RO", "RR", "SC", "SP", "SE", "TO" ] }, "postal_code": { "description": "Payer's postal code. Must be eight digits long, however an optional dash could be applied after the 5th digit ([more information about the format available here](https://en.wikipedia.org/wiki/List_of_postal_codes_in_Brazil)). Both options are accepted as correct.", "type": "string", "example": "20000-000", "pattern": "^\\d{5}-?\\d{3}$" } } } } } }, "required": [ "checkout_reference", "amount", "currency", "merchant_code" ] }, "CheckoutCreate": { "description": "Details of the payment checkout.", "type": "object", "properties": { "checkout_reference": { "description": "Unique ID of the payment checkout specified by the client application when creating the checkout resource.", "type": "string", "maxLength": 90 }, "amount": { "description": "Amount of the payment.", "type": "number", "format": "float" }, "currency": { "$ref": "#/components/schemas/Currency" }, "pay_to_email": { "description": "Email address of the registered user (merchant) to whom the payment is made.", "type": "string", "format": "email", "deprecated": true, "x-deprecation-notice": "`pay_to_email` is deprecated, use `merchant_code` instead." }, "merchant_code": { "description": "Unique identifying code of the merchant profile.", "type": "string" }, "description": { "description": "Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.", "type": "string" }, "return_url": { "description": "URL to which the SumUp platform sends the processing status of the payment checkout.", "type": "string", "format": "uri" }, "id": { "description": "Unique ID of the checkout resource.", "type": "string", "readOnly": true }, "status": { "description": "Current status of the checkout.", "type": "string", "enum": [ "PENDING", "FAILED", "PAID" ], "readOnly": true }, "date": { "description": "Date and time of the creation of the payment checkout. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.", "type": "string", "format": "date-time", "example": "2020-02-29T10:56:56+00:00", "readOnly": true }, "valid_until": { "description": "Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.", "type": "string", "format": "date-time", "example": "2020-02-29T10:56:56+00:00", "nullable": true, "readOnly": true }, "transactions": { "description": "List of transactions related to the payment.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/TransactionMixinBase" }, { "$ref": "#/components/schemas/TransactionMixinCheckout" } ] }, "readOnly": true, "uniqueItems": true }, "redirect_url": { "description": "Required for 3DS checkouts. Refers to a URL where the end user is redirected once the payment processing completes.", "type": "string", "example": "https://mysite.com/completed_purchase" } }, "required": [ "checkout_reference", "amount", "currency", "merchant_code", "id", "status", "date", "transactions" ] }, "CheckoutProcessMixin": { "description": "Details of the payment instrument for processing the checkout.", "type": "object", "properties": { "payment_type": { "type": "string", "enum": [ "card", "boleto", "ideal", "blik", "bancontact" ] }, "installments": { "description": "Number of installments for deferred payments. Available only to merchant users in Brazil.", "type": "integer", "maximum": 12, "minimum": 1 }, "mandate": { "$ref": "#/components/schemas/MandatePayload" }, "card": { "$ref": "#/components/schemas/Card" }, "token": { "description": "__Required when using a tokenized card to process a checkout.__ Unique token identifying the saved payment card for a customer.", "type": "string" }, "customer_id": { "description": "__Required when `token` is provided.__ Unique ID of the customer.", "type": "string" } }, "required": [ "payment_type" ] }, "CheckoutSuccess": { "allOf": [ { "$ref": "#/components/schemas/Checkout" }, { "type": "object", "properties": { "transaction_code": { "description": "Transaction code of the successful transaction with which the payment for the checkout is completed.", "type": "string", "example": "TEENSK4W2K", "readOnly": true }, "transaction_id": { "description": "Transaction ID of the successful transaction with which the payment for the checkout is completed.", "type": "string", "example": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "readOnly": true }, "merchant_name": { "description": "Name of the merchant", "type": "string", "example": "Sample Merchant" }, "redirect_url": { "description": "Refers to a url where the end user is redirected once the payment processing completes.", "type": "string", "example": "https://mysite.com/completed_purchase" }, "payment_instrument": { "description": "Object containing token information for the specified payment instrument", "type": "object", "properties": { "token": { "description": "Token value", "type": "string", "example": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc" } } } } } ] }, "CheckoutSuccessToken": { "description": "Details of the payment checkout.", "type": "object", "properties": { "checkout_reference": { "description": "Unique ID of the payment checkout specified by the client application when creating the checkout resource.", "type": "string", "maxLength": 90 }, "amount": { "description": "Amount of the payment.", "type": "number", "format": "float", "example": 10.1 }, "currency": { "$ref": "#/components/schemas/Currency" }, "pay_to_email": { "description": "Email address of the registered user (merchant) to whom the payment is made.", "type": "string", "format": "email", "deprecated": true, "x-deprecation-notice": "`pay_to_email` is deprecated, use `merchant_code` instead." }, "merchant_code": { "description": "Unique identifying code of the merchant profile.", "type": "string" }, "description": { "description": "Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.", "type": "string" }, "id": { "description": "Unique ID of the checkout resource.", "type": "string", "readOnly": true }, "status": { "description": "Current status of the checkout.", "type": "string", "enum": [ "PENDING", "FAILED", "PAID" ], "readOnly": true }, "date": { "description": "Date and time of the creation of the payment checkout. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.", "type": "string", "format": "date-time", "example": "2020-02-29T10:56:56+00:00", "readOnly": true }, "transaction_code": { "description": "Transaction code of the successful transaction with which the payment for the checkout is completed.", "type": "string", "example": "TEENSK4W2K", "readOnly": true }, "transaction_id": { "description": "Transaction ID of the successful transaction with which the payment for the checkout is completed.", "type": "string", "example": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "readOnly": true }, "merchant_name": { "description": "Name of the merchant", "type": "string", "example": "Sample Merchant" }, "redirect_url": { "description": "Refers to a url where the end user is redirected once the payment processing completes.", "type": "string", "example": "https://mysite.com/completed_purchase" }, "customer_id": { "description": "Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.", "type": "string" }, "payment_instrument": { "description": "Object containing token information for the specified payment instrument", "type": "object", "properties": { "token": { "description": "Token value", "type": "string", "example": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc" } } }, "transactions": { "description": "List of transactions related to the payment.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/TransactionMixinBase" }, { "$ref": "#/components/schemas/TransactionMixinCheckout" } ] }, "readOnly": true, "uniqueItems": true } } }, "CheckoutAccepted": { "description": "3DS Response", "type": "object", "properties": { "next_step": { "description": "Required action processing 3D Secure payments.", "type": "object", "properties": { "url": { "description": "Where the end user is redirected.", "type": "string", "example": "https://dummy-3ds-gateway.com/cap?RID=1233&VAA=A" }, "method": { "description": "Method used to complete the redirect.", "type": "string", "example": "POST" }, "redirect_url": { "description": "Refers to a url where the end user is redirected once the payment processing completes.", "type": "string", "example": "https://mysite.com/completed_purchase" }, "mechanism": { "description": "Indicates allowed mechanisms for redirecting an end user. If both values are provided to ensure a redirect takes place in either.", "type": "array", "items": { "type": "string", "enum": [ "iframe", "browser" ] } }, "payload": { "description": "Contains parameters essential for form redirection. Number of object keys and their content can vary.", "type": "object", "properties": { "PaReq": { "example": "eJxVUttu2zAM/RXDr4MjyY5dO6BVuE27FZuDZHGG9VGRmMSFb/Wljff1k9KkF0APPCR1eHQouD6WhfWCbZfXVWyzCbUtrGSt8mof25vs3gltq+tFpURRVxjbI3b2NYfs0CLO1yiHFjmk2HVij1auYrsRW1+F0U4qZxfKwJlur4QTYcQcJoIdc+XO2/poc1gmv/GZw3k216MnLpAL1JytPIiq5yDk883Dgk+DwPV9IGcIJbYPc84o1Ye6lHqu5wVA3tJQiRL5eiiHxlqKscSq76xfeZn3qICciiDroerbkYeuvnYBMLQFP/R9MyOkM9cnCoGYJJAPScvBRJ0mOeaKr/6l08XT6jXN7tx0vvHSbOMtsj1dzB9jIKYDlOiRu1omYyy0WDCj0YxFQE55EKWZzj2f6ee9xdCYEcmnwucEaN9bvaeRR1ehFn9BgMdGr0l3aCvfYyAfem9/GENlrz36ufpTBPTv07r8lm3qpPiOo1y/7u+SJImNzacmw5hrX1wt/kRpABBDQ84bJOf16+jLt/gPhUvGGw==" }, "MD": { "example": "b1a536c0-29b9-11eb-adc1-0242ac120002" }, "TermUrl": { "example": "https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572/complete_payment" } } } } } } }, "CreateReaderCheckout": { "description": "Reader Checkout", "type": "object", "properties": { "description": { "description": "Description of the checkout to be shown in the Merchant Sales\n", "type": "string" }, "card_type": { "description": "The card type of the card used for the transaction.\nIs is required only for some countries (e.g: Brazil).\n", "type": "string", "example": "credit", "enum": [ "credit", "debit" ] }, "installments": { "description": "Number of installments for the transaction.\nIt may vary according to the merchant country.\nFor example, in Brazil, the maximum number of installments is 12.\n", "type": "integer", "example": 1 }, "return_url": { "description": "Webhook URL to which the payment result will be sent.\nIt must be a HTTPS url.\n", "type": "string", "format": "uri", "example": "https://www.example.com" }, "total_amount": { "$ref": "#/components/schemas/CreateReaderCheckoutAmount" }, "tip_rates": { "description": "List of tipping rates to be displayed to the cardholder.\nThe rates are in percentage and should be between 0.01 and 0.99.\nThe list should be sorted in ascending order.\n", "type": "array", "items": { "type": "number", "format": "float", "multipleOf": 0.01 } }, "affiliate": { "$ref": "#/components/schemas/Affiliate" } }, "required": [ "total_amount" ], "title": "Reader" }, "CreateReaderCheckoutAmount": { "description": "Amount of the transaction.\nThe amount is represented as an integer value altogether with the currency and the minor unit.\nFor example, EUR 1.00 is represented as value 100 with minor unit of 2.\n", "type": "object", "properties": { "value": { "description": "Total amount of the transaction.\nIt must be a positive integer.\n", "type": "integer", "example": 1000 }, "currency": { "description": "Currency ISO 4217 code", "type": "string", "example": "EUR" }, "minor_unit": { "description": "The minor units of the currency. It represents the number of decimals of the currency.\nFor the currencies CLP, COP and HUF, the minor unit is 0.\n", "type": "integer", "example": 2 } }, "required": [ "value", "currency", "minor_unit" ] }, "ReaderCheckoutStatusChange": { "description": "The callback payload containing the status change of the Reader Checkout.\n", "type": "object", "properties": { "id": { "description": "The unique event id.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "event_type": { "description": "The event type.", "type": "string", "example": "solo.transaction.updated" }, "payload": { "description": "The event payload.", "type": "object", "properties": { "client_transaction_id": { "description": "The unique client transaction id. It is the same returned by the Checkout.", "type": "string", "format": "uuid", "example": "ba0a3c07-799e-40f8-89e9-1dfe96e4557e" }, "merchant_code": { "description": "The target merchant code owner of the transaction.", "type": "string", "example": "M1234567" }, "status": { "description": "The status of the transaction.", "type": "string", "example": "successful", "enum": [ "successful", "failed" ] }, "transaction_id": { "description": "The unique transaction id.", "type": "string", "format": "uuid", "example": "c88032e4-a384-4030-943c-ac59cc768d90", "deprecated": true } }, "required": [ "client_transaction_id", "merchant_code", "status" ] }, "timestamp": { "description": "The timestamp of the event.", "type": "string", "format": "date-time", "example": "2021-01-01T00:00:00Z" } }, "required": [ "id", "event_type", "payload", "timestamp" ] }, "Customer": { "type": "object", "properties": { "customer_id": { "description": "Unique ID of the customer.", "type": "string", "example": "831ff8d4cd5958ab5670" }, "personal_details": { "$ref": "#/components/schemas/PersonalDetails" } }, "required": [ "customer_id" ], "title": "Customer" }, "CountryDetails": { "description": "Country Details", "type": "object", "properties": { "currency": { "description": "Currency ISO 4217 code", "type": "string" }, "iso_code": { "description": "Country ISO code", "type": "string" }, "en_name": { "description": "Country EN name", "type": "string" }, "native_name": { "description": "Country native name", "type": "string" } } }, "DoingBusinessAs": { "description": "Doing Business As information", "type": "object", "properties": { "business_name": { "description": "Doing business as name", "type": "string" }, "company_registration_number": { "description": "Doing business as company registration number", "type": "string" }, "vat_id": { "description": "Doing business as VAT ID", "type": "string" }, "website": { "description": "Doing business as website", "type": "string" }, "email": { "description": "Doing business as email", "type": "string" }, "address": { "type": "object", "properties": { "address_line1": { "description": "Address line 1", "type": "string" }, "address_line2": { "description": "Address line 2", "type": "string" }, "city": { "description": "City", "type": "string" }, "country": { "description": "Country ISO 3166-1 code", "type": "string" }, "region_id": { "description": "Country region ID", "type": "number" }, "region_name": { "description": "Country region name", "type": "string" }, "post_code": { "description": "Postal code", "type": "string" } } } } }, "DoingBusinessAsPayload": { "description": "Doing Business As information", "type": "object", "properties": { "business_name": { "description": "Doing business as name", "type": "string" }, "tax_id": { "description": "Doing business as Tax ID", "type": "string" }, "vat_id": { "description": "Doing business as VAT ID", "type": "string" }, "website": { "description": "Doing business as website", "type": "string" }, "email": { "description": "Doing business as email", "type": "string" }, "address": { "$ref": "#/components/schemas/AddressPayload" } } }, "Error": { "description": "Error message structure.", "type": "object", "properties": { "message": { "description": "Short description of the error.", "type": "string" }, "error_code": { "description": "Platform code for the error.", "type": "string" } } }, "ErrorExtended": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "param": { "description": "Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example, `card.name` refers to the `name` parameter embedded in the `card` object.", "type": "string" } } } ] }, "ErrorForbidden": { "description": "Error message for forbidden requests.", "type": "object", "properties": { "error_message": { "description": "Short description of the error.", "type": "string" }, "error_code": { "description": "Platform code for the error.", "type": "string" }, "status_code": { "description": "HTTP status code for the error.", "type": "string" } } }, "DetailsError": { "description": "Error message structure.", "type": "object", "properties": { "title": { "description": "Short title of the error.", "type": "string" }, "details": { "description": "Details of the error.", "type": "string" }, "status": { "description": "The status code.", "type": "number" }, "failed_constraints": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "reference": { "type": "string" } } } } } }, "Event": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/EventID" }, "transaction_id": { "$ref": "#/components/schemas/TransactionID" }, "type": { "$ref": "#/components/schemas/EventType" }, "status": { "$ref": "#/components/schemas/EventStatus" }, "amount": { "$ref": "#/components/schemas/AmountEvent" }, "timestamp": { "$ref": "#/components/schemas/TimestampEvent" }, "fee_amount": { "description": "Amount of the fee related to the event.", "type": "number", "format": "float" }, "installment_number": { "description": "Consecutive number of the installment.", "type": "integer" }, "deducted_amount": { "description": "Amount deducted for the event.", "type": "number", "format": "float" }, "deducted_fee_amount": { "description": "Amount of the fee deducted for the event.", "type": "number", "format": "float" } } }, "FinancialPayouts": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" }, "date": { "type": "string", "format": "date" }, "fee": { "type": "number", "format": "float" }, "id": { "type": "integer" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "SUCCESSFUL", "FAILED" ] }, "transaction_code": { "type": "string" }, "type": { "type": "string", "enum": [ "PAYOUT", "CHARGE_BACK_DEDUCTION", "REFUND_DEDUCTION", "DD_RETURN_DEDUCTION", "BALANCE_DEDUCTION" ] } } }, "title": "Financial Payouts" }, "LegalType": { "description": "Id of the legal type of the merchant profile", "type": "object", "properties": { "id": { "description": "Unique id", "type": "number" }, "full_description": { "description": "Legal type description", "type": "string" }, "description": { "description": "Legal type short description", "type": "string" }, "sole_trader": { "description": "Sole trader legal type if true", "type": "boolean" } } }, "Link": { "description": "Details of a link to a related resource.", "type": "object", "properties": { "rel": { "description": "Specifies the relation to the current resource.", "type": "string" }, "href": { "description": "URL for accessing the related resource.", "type": "string", "format": "uri" }, "type": { "description": "Specifies the media type of the related resource.", "type": "string" } } }, "MandatePayload": { "description": "Mandate is passed when a card is to be tokenized", "type": "object", "properties": { "type": { "description": "Indicates the mandate type", "type": "string", "enum": [ "recurrent" ] }, "user_agent": { "description": "Operating system and web client used by the end-user", "type": "string" }, "user_ip": { "description": "IP address of the end user. Supports IPv4 and IPv6", "type": "string" } }, "example": { "type": "recurrent", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36", "user_ip": "172.217.169.174" }, "required": [ "type", "user_agent" ] }, "MandateResponse": { "description": "Created mandate", "type": "object", "properties": { "type": { "description": "Indicates the mandate type", "type": "string" }, "status": { "description": "Mandate status", "type": "string" }, "merchant_code": { "description": "Merchant code which has the mandate", "type": "string" } }, "example": { "type": "recurrent", "status": "active", "merchant_code": "MDASYTPD" } }, "MerchantAccount": { "description": "Details of the merchant account.", "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" }, "personal_profile": { "$ref": "#/components/schemas/PersonalProfile" }, "merchant_profile": { "$ref": "#/components/schemas/MerchantProfile" }, "app_settings": { "$ref": "#/components/schemas/AppSettings" }, "permissions": { "$ref": "#/components/schemas/Permissions" }, "is_migrated_payleven_br": { "description": "Merchant comes from payleven BR migration", "type": "boolean" } }, "title": "Merchant Account" }, "MerchantProfile": { "description": "Account's merchant profile", "type": "object", "properties": { "merchant_code": { "description": "Unique identifying code of the merchant profile", "type": "string" }, "company_name": { "description": "Company name", "type": "string" }, "website": { "description": "Website", "type": "string" }, "legal_type": { "$ref": "#/components/schemas/LegalType" }, "merchant_category_code": { "description": "Merchant category code", "type": "string" }, "mobile_phone": { "description": "Mobile phone number", "type": "string" }, "company_registration_number": { "description": "Company registration number", "type": "string" }, "vat_id": { "description": "Vat ID", "type": "string" }, "permanent_certificate_access_code": { "description": "Permanent certificate access code (Portugal)", "type": "string" }, "nature_and_purpose": { "description": "Nature and purpose of the business", "type": "string" }, "address": { "$ref": "#/components/schemas/AddressWithDetails" }, "business_owners": { "$ref": "#/components/schemas/BusinessOwners" }, "doing_business_as": { "$ref": "#/components/schemas/DoingBusinessAs" }, "settings": { "$ref": "#/components/schemas/MerchantSettings" }, "vat_rates": { "$ref": "#/components/schemas/VatRates" }, "locale": { "description": "Merchant locale (for internal usage only)", "type": "string" }, "bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccount" } }, "extdev": { "description": "True if the merchant is extdev", "type": "boolean" }, "payout_zone_migrated": { "description": "True if the payout zone of this merchant is migrated", "type": "boolean" }, "country": { "description": "Merchant country code formatted according to [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (for internal usage only)", "type": "string" } } }, "MerchantProfilePayload": { "description": "Account's merchant profile", "type": "object", "properties": { "legal_type_id": { "description": "Id of the legal type of the merchant", "type": "number" }, "merchant_category_code": { "description": "Merchant category code", "type": "string" }, "company_name": { "description": "Company name", "type": "string" }, "company_registration_number": { "description": "Company registration number", "type": "string" }, "vat_id": { "description": "Vat ID", "type": "string" }, "permanent_certificate_access_code": { "description": "Payment certificate access code", "type": "string" }, "website": { "description": "Company website", "type": "string" }, "nature_and_purpose": { "description": "Nature and purpose of the business. Required for the following merchant category codes: 5999, 7392, 8999, 5694, 5969, 7299, 7399", "type": "string" }, "mobile_phone": { "description": "Mobile number", "type": "string" }, "address": { "$ref": "#/components/schemas/AddressPayload" }, "doing_business_as": { "type": "object", "properties": { "business_name": { "description": "Doing business as name", "type": "string" }, "tax_id": { "description": "Doing business as Tax ID", "type": "string" }, "vat_id": { "description": "Doing business as Vat ID", "type": "string" }, "website": { "description": "Doing business as website", "type": "string" }, "email": { "description": "Doing business as email", "type": "string" }, "address": { "$ref": "#/components/schemas/AddressPayload" } } }, "business_owners": { "$ref": "#/components/schemas/BusinessOwners" }, "is_test_account": { "description": "Defines if the profile nature is for testing", "type": "boolean" } }, "required": [ "legal_type_id", "company_registration_number", "merchant_category_code", "company_name", "address" ] }, "MerchantSettings": { "description": "Merchant settings (like \\\"payout_type\\\", \\\"payout_period\\\")", "type": "object", "properties": { "tax_enabled": { "description": "Whether to show tax in receipts (saved per transaction)", "type": "boolean" }, "payout_type": { "description": "Payout type", "type": "string" }, "payout_period": { "description": "Payout frequency", "type": "string" }, "payout_on_demand_available": { "description": "Whether merchant can edit payouts on demand", "type": "boolean" }, "payout_on_demand": { "description": "Whether merchant will receive payouts on demand", "type": "boolean" }, "printers_enabled": { "description": "Whether to show printers in mobile app", "type": "boolean" }, "payout_instrument": { "description": "Payout Instrument", "type": "string" }, "moto_payment": { "description": "Whether merchant can make MOTO payments", "type": "string", "enum": [ "UNAVAILABLE", "ENFORCED", "ON", "OFF" ] }, "stone_merchant_code": { "description": "Stone merchant code", "type": "string" }, "daily_payout_email": { "description": "Whether merchant will receive daily payout emails", "type": "boolean" }, "monthly_payout_email": { "description": "Whether merchant will receive monthly payout emails", "type": "boolean" }, "gross_settlement": { "description": "Whether merchant has gross settlement enabled", "type": "boolean" } } }, "MerchantSettingsPayload": { "type": "object", "properties": { "payout_period": { "description": "Payout period.", "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "payout_type": { "description": "Payout type.", "type": "string", "enum": [ "SINGLE_PAYMENT" ] }, "payout_on_demand": { "description": "If true, the merchant will not receive automatic payouts.", "type": "boolean" }, "payout_on_demand_available": { "description": "If true, the merchant will be able to manage payout_on_demand settings", "type": "string" }, "expected_max_transaction_amount": { "description": "Expected maximum amount of a single purchase", "type": "number" }, "printers_enabled": { "description": "Printers enabled.", "type": "boolean" }, "gross_settlement": { "description": "Gross settlement", "type": "boolean" } } }, "PaymentInstrumentCard": { "description": "Details of the payment card that is saved as a payment instrument.", "type": "object", "properties": { "token": { "description": "Unique token identifying the saved payment card for a customer.", "type": "string", "readOnly": true }, "active": { "description": "Indicates whether the payment instrument is active and can be used for payments. To deactivate it, send a `DELETE` request to the resource endpoint.", "type": "boolean", "default": true, "readOnly": true }, "type": { "description": "Type of the payment instrument.", "type": "string", "enum": [ "card" ] }, "card": { "$ref": "#/components/schemas/Card" } }, "required": [ "token", "active", "type", "card" ] }, "PaymentInstrumentResponse": { "description": "Payment Instrument Response", "type": "object", "properties": { "token": { "description": "Unique token identifying the saved payment card for a customer.", "type": "string", "readOnly": true }, "active": { "description": "Indicates whether the payment instrument is active and can be used for payments. To deactivate it, send a `DELETE` request to the resource endpoint.", "type": "boolean", "default": true, "readOnly": true }, "type": { "description": "Type of the payment instrument.", "type": "string", "enum": [ "card" ] }, "card": { "description": "Details of the payment card.", "type": "object", "properties": { "last_4_digits": { "description": "Last 4 digits of the payment card number.", "type": "string", "example": "3456", "maxLength": 4, "minLength": 4, "readOnly": true }, "type": { "description": "Issuing card network of the payment card.", "type": "string", "enum": [ "AMEX", "CUP", "DINERS", "DISCOVER", "ELO", "ELV", "HIPERCARD", "JCB", "MAESTRO", "MASTERCARD", "VISA", "VISA_ELECTRON", "VISA_VPAY", "UNKNOWN" ], "readOnly": true } } }, "mandate": { "$ref": "#/components/schemas/MandateResponse" }, "created_at": { "description": "Creation date of payment instrument. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.", "type": "string", "format": "date-time" } }, "example": { "token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3", "active": true, "type": "card", "mandate": { "type": "recurrent", "status": "active", "merchant_code": "MDASYTPD" }, "card": { "last_4_digits": "0001", "type": "VISA" }, "created_at": "2021-03-30T10:06:07.000+00:00" } }, "Permissions": { "description": "User permissions", "type": "object", "properties": { "create_moto_payments": { "description": "Create MOTO payments", "type": "boolean" }, "full_transaction_history_view": { "description": "Can view full merchant transaction history", "type": "boolean" }, "refund_transactions": { "description": "Refund transactions", "type": "boolean" }, "create_referral": { "description": "Create referral", "type": "boolean" } } }, "PersonalDetails": { "description": "Personal details for the customer.", "type": "object", "properties": { "first_name": { "description": "First name of the customer.", "type": "string", "example": "John" }, "last_name": { "description": "Last name of the customer.", "type": "string", "example": "Doe" }, "email": { "description": "Email address of the customer.", "type": "string", "example": "user@example.com" }, "phone": { "description": "Phone number of the customer.", "type": "string", "example": "+491635559723" }, "birthdate": { "description": "Date of birth of the customer.", "type": "string", "format": "date", "example": "1993-12-31" }, "address": { "$ref": "#/components/schemas/Address" } } }, "PersonalDetailsResponse": { "description": "Personal details for the customer.", "type": "object", "properties": { "first_name": { "description": "First name of the customer.", "type": "string", "example": "John" }, "last_name": { "description": "Last name of the customer.", "type": "string", "example": "Doe" }, "email": { "description": "Email address of the customer.", "type": "string", "example": "user@example.com" }, "phone": { "description": "Phone number of the customer.", "type": "string", "example": "+491635559723" }, "birthdate": { "description": "Date of birth of the customer.", "type": "string", "format": "date", "example": "1993-12-31" }, "address": { "$ref": "#/components/schemas/AddressResponse" } } }, "PersonalProfile": { "description": "Account's personal profile.", "type": "object", "properties": { "first_name": { "description": "First name of the user", "type": "string" }, "last_name": { "description": "Last name of the user", "type": "string" }, "date_of_birth": { "description": "Date of birth", "type": "string" }, "mobile_phone": { "description": "Mobile phone number", "type": "string" }, "address": { "$ref": "#/components/schemas/AddressWithDetails" }, "complete": { "type": "boolean" } } }, "PersonalProfilePayload": { "description": "Account's personal profile.", "type": "object", "properties": { "first_name": { "description": "First name of the user", "type": "string" }, "last_name": { "description": "Last name of the user", "type": "string" }, "date_of_birth": { "description": "Date of birth", "type": "string", "format": "date" }, "mobile_phone": { "description": "Mobile phone number", "type": "string" }, "national_id": { "description": "National identification id. Country specific. Ex CPF (Brazil), DNI (Spain), PESEL (Poland)", "type": "string" }, "address": { "$ref": "#/components/schemas/AddressPayload" } }, "required": [ "first_name", "last_name", "date_of_birth", "address" ] }, "Product": { "description": "Details of the product for which the payment is made.", "type": "object", "properties": { "name": { "description": "Name of the product from the merchant's catalog.", "type": "string" }, "price": { "description": "Price of the product without VAT.", "type": "number", "format": "float" }, "vat_rate": { "description": "VAT rate applicable to the product.", "type": "number", "format": "float" }, "single_vat_amount": { "description": "Amount of the VAT for a single product item (calculated as the product of `price` and `vat_rate`, i.e. `single_vat_amount = price * vat_rate`).", "type": "number", "format": "float" }, "price_with_vat": { "description": "Price of a single product item with VAT.", "type": "number", "format": "float" }, "vat_amount": { "description": "Total VAT amount for the purchase (calculated as the product of `single_vat_amount` and `quantity`, i.e. `vat_amount = single_vat_amount * quantity`).", "type": "number", "format": "float" }, "quantity": { "description": "Number of product items for the purchase.", "type": "number" }, "total_price": { "description": "Total price of the product items without VAT (calculated as the product of `price` and `quantity`, i.e. `total_price = price * quantity`).", "type": "number", "format": "float" }, "total_with_vat": { "description": "Total price of the product items including VAT (calculated as the product of `price_with_vat` and `quantity`, i.e. `total_with_vat = price_with_vat * quantity`).", "type": "number", "format": "float" } } }, "Receipt": { "type": "object", "properties": { "transaction_data": { "$ref": "#/components/schemas/ReceiptTransaction" }, "merchant_data": { "$ref": "#/components/schemas/ReceiptMerchantData" }, "emv_data": { "type": "object" }, "acquirer_data": { "type": "object", "properties": { "tid": { "type": "string" }, "authorization_code": { "type": "string" }, "return_code": { "type": "string" }, "local_time": { "type": "string" } } } }, "title": "Receipt" }, "ReceiptEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/EventID" }, "transaction_id": { "$ref": "#/components/schemas/TransactionID" }, "type": { "$ref": "#/components/schemas/EventType" }, "status": { "$ref": "#/components/schemas/EventStatus" }, "amount": { "$ref": "#/components/schemas/AmountEvent" }, "timestamp": { "$ref": "#/components/schemas/TimestampEvent" }, "receipt_no": { "type": "string" } } }, "ReceiptCard": { "type": "object", "properties": { "last_4_digits": { "description": "Card last 4 digits.", "type": "string" }, "type": { "description": "Card Scheme.", "type": "string" } } }, "ReceiptMerchantData": { "description": "Receipt merchant data", "type": "object", "properties": { "merchant_profile": { "type": "object", "properties": { "merchant_code": { "type": "string" }, "business_name": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "object", "properties": { "address_line1": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "country_en_name": { "type": "string" }, "country_native_name": { "type": "string" }, "post_code": { "type": "string" }, "landline": { "type": "string" } } } } }, "locale": { "type": "string" } } }, "ReceiptTransaction": { "description": "Transaction information.", "type": "object", "properties": { "transaction_code": { "description": "Transaction code.", "type": "string" }, "amount": { "description": "Transaction amount.", "type": "string" }, "vat_amount": { "description": "Transaction VAT amount.", "type": "string" }, "tip_amount": { "description": "Tip amount (included in transaction amount).", "type": "string" }, "currency": { "description": "Transaction currency.", "type": "string" }, "timestamp": { "description": "Time created at.", "type": "string", "format": "date-time" }, "status": { "description": "Transaction processing status.", "type": "string" }, "payment_type": { "description": "Transaction type.", "type": "string" }, "entry_mode": { "description": "Transaction entry mode.", "type": "string" }, "verification_method": { "description": "Cardholder verification method.", "type": "string" }, "card": { "$ref": "#/components/schemas/ReceiptCard" }, "installments_count": { "description": "Number of installments.", "type": "integer" }, "products": { "description": "Products", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Product name.", "type": "string" }, "description": { "description": "Product description.", "type": "string" }, "price": { "description": "Product price.", "type": "number", "format": "float" }, "quantity": { "description": "Product quantity.", "type": "integer" }, "total_price": { "description": "Quantity x product price.", "type": "number", "format": "float" } } } }, "vat_rates": { "description": "Vat rates.", "type": "array", "items": { "type": "object", "properties": { "gross": { "description": "Gross", "type": "number", "format": "float" }, "net": { "description": "Net", "type": "number", "format": "float" }, "rate": { "description": "Rate", "type": "number", "format": "float" }, "vat": { "description": "Vat", "type": "number", "format": "float" } } } }, "events": { "description": "Events", "type": "array", "items": { "$ref": "#/components/schemas/ReceiptEvent" } }, "receipt_no": { "description": "Receipt number", "type": "string" } } }, "TimeoffsetDetails": { "description": "TimeOffset Details", "type": "object", "properties": { "post_code": { "description": "Postal code", "type": "string" }, "offset": { "description": "UTC offset", "type": "number" }, "dst": { "description": "Daylight Saving Time", "type": "boolean" } } }, "TransactionEvent": { "description": "Details of a transaction event.", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/EventID" }, "event_type": { "$ref": "#/components/schemas/EventType" }, "status": { "$ref": "#/components/schemas/EventStatus" }, "amount": { "$ref": "#/components/schemas/AmountEvent" }, "due_date": { "description": "Date when the transaction event is due to occur.", "type": "string", "format": "date" }, "date": { "description": "Date when the transaction event occurred.", "type": "string", "format": "date" }, "installment_number": { "description": "Consecutive number of the installment that is paid. Applicable only payout events, i.e. `event_type = PAYOUT`.", "type": "integer" }, "timestamp": { "$ref": "#/components/schemas/TimestampEvent" } } }, "TransactionMixinBase": { "description": "Details of the transaction.", "type": "object", "properties": { "id": { "description": "Unique ID of the transaction.", "type": "string", "example": "6b425463-3e1b-431d-83fa-1e51c2925e99" }, "transaction_code": { "description": "Transaction code returned by the acquirer/processing entity after processing the transaction.", "type": "string", "example": "TEENSK4W2K" }, "amount": { "description": "Total amount of the transaction.", "type": "number", "format": "float", "example": 10.1 }, "currency": { "$ref": "#/components/schemas/Currency" }, "timestamp": { "description": "Date and time of the creation of the transaction. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.", "type": "string", "format": "date-time", "example": "2020-02-29T10:56:56.876Z" }, "status": { "description": "Current status of the transaction.", "type": "string", "enum": [ "SUCCESSFUL", "CANCELLED", "FAILED", "PENDING" ] }, "payment_type": { "description": "Payment type used for the transaction.", "type": "string", "enum": [ "ECOM", "RECURRING", "BOLETO" ] }, "installments_count": { "description": "Current number of the installment for deferred payments.", "type": "integer", "minimum": 1 } } }, "TransactionMixinCheckout": { "type": "object", "properties": { "merchant_code": { "description": "Unique code of the registered merchant to whom the payment is made.", "type": "string", "example": "MH4H92C7" }, "vat_amount": { "description": "Amount of the applicable VAT (out of the total transaction amount).", "type": "number", "format": "float", "example": 6 }, "tip_amount": { "description": "Amount of the tip (out of the total transaction amount).", "type": "number", "format": "float", "example": 3 }, "entry_mode": { "description": "Entry mode of the payment details.", "type": "string", "enum": [ "CUSTOMER_ENTRY", "BOLETO" ] }, "auth_code": { "description": "Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.", "type": "string", "example": "053201" }, "internal_id": { "description": "Internal unique ID of the transaction on the SumUp platform.", "type": "integer", "example": 1763892018 } } }, "TransactionMixinHistory": { "type": "object", "properties": { "product_summary": { "description": "Short description of the payment. The value is taken from the `description` property of the related checkout resource.", "type": "string" }, "payouts_total": { "description": "Total number of payouts to the registered user specified in the `user` property.", "type": "integer" }, "payouts_received": { "description": "Number of payouts that are made to the registered user specified in the `user` property.", "type": "integer" }, "payout_plan": { "description": "Payout plan of the registered user at the time when the transaction was made.", "type": "string", "enum": [ "SINGLE_PAYMENT", "TRUE_INSTALLMENT", "ACCELERATED_INSTALLMENT" ] } } }, "TransactionHistory": { "allOf": [ { "$ref": "#/components/schemas/TransactionMixinBase" }, { "$ref": "#/components/schemas/TransactionMixinHistory" }, { "type": "object", "properties": { "transaction_id": { "$ref": "#/components/schemas/TransactionID" }, "client_transaction_id": { "description": "Client-specific ID of the transaction.", "type": "string" }, "user": { "description": "Email address of the registered user (merchant) to whom the payment is made.", "type": "string", "format": "email" }, "type": { "description": "Type of the transaction for the registered user specified in the `user` property.", "type": "string", "enum": [ "PAYMENT", "REFUND", "CHARGE_BACK" ] }, "card_type": { "description": "Issuing card network of the payment card used for the transaction.", "type": "string", "enum": [ "VISA", "AMEX", "CUP", "DINERS", "DISCOVER", "ELO", "ELV", "HIPERCARD", "JCB", "MAESTRO", "MASTERCARD", "VISA_ELECTRON", "VISA_VPAY", "UNKNOWN" ] } } } ] }, "TransactionFull": { "allOf": [ { "$ref": "#/components/schemas/TransactionMixinBase" }, { "$ref": "#/components/schemas/TransactionMixinCheckout" }, { "$ref": "#/components/schemas/TransactionMixinHistory" }, { "type": "object", "properties": { "username": { "description": "Email address of the registered user (merchant) to whom the payment is made.", "type": "string", "format": "email" }, "lat": { "$ref": "#/components/schemas/Lat" }, "lon": { "$ref": "#/components/schemas/Lon" }, "horizontal_accuracy": { "$ref": "#/components/schemas/HorizontalAccuracy" }, "simple_payment_type": { "description": "Simple name of the payment type.", "type": "string", "enum": [ "MOTO", "CASH", "CC_SIGNATURE", "ELV", "CC_CUSTOMER_ENTERED", "MANUAL_ENTRY", "EMV" ] }, "verification_method": { "description": "Verification method used for the transaction.", "type": "string", "enum": [ "none", "signature", "offline pin", "online pin", "offline pin + signature", "confirmation code verified" ] }, "card": { "$ref": "#/components/schemas/CardResponse" }, "local_time": { "description": "Local date and time of the creation of the transaction.", "type": "string", "format": "date-time" }, "payout_type": { "description": "Payout type for the transaction.", "type": "string", "enum": [ "BANK_ACCOUNT", "BALANCE", "PREPAID_CARD" ] }, "products": { "description": "List of products from the merchant's catalogue for which the transaction serves as a payment.", "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "vat_rates": { "description": "List of VAT rates applicable to the transaction.", "type": "array", "items": {} }, "transaction_events": { "description": "List of transaction events related to the transaction.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionEvent" } }, "simple_status": { "description": "Status generated from the processing status and the latest transaction state.", "type": "string", "enum": [ "SUCCESSFUL", "PAID_OUT", "CANCEL_FAILED", "CANCELLED", "CHARGEBACK", "FAILED", "REFUND_FAILED", "REFUNDED", "NON_COLLECTION" ] }, "links": { "description": "List of hyperlinks for accessing related resources.", "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "$ref": "#/components/schemas/LinkRefund" } ] }, "uniqueItems": true }, "events": { "description": "List of events related to the transaction.", "type": "array", "items": { "$ref": "#/components/schemas/Event" }, "uniqueItems": true }, "location": { "description": "Details of the payment location as received from the payment terminal.", "type": "object", "properties": { "lat": { "$ref": "#/components/schemas/Lat" }, "lon": { "$ref": "#/components/schemas/Lon" }, "horizontal_accuracy": { "$ref": "#/components/schemas/HorizontalAccuracy" } } }, "tax_enabled": { "description": "Indicates whether tax deduction is enabled for the transaction.", "type": "boolean" } } } ] }, "VatRates": { "description": "Merchant VAT rates", "type": "object", "properties": { "id": { "description": "Internal ID", "type": "number" }, "description": { "description": "Description", "type": "string" }, "rate": { "description": "Rate", "type": "number" }, "ordering": { "description": "Ordering", "type": "number" }, "country": { "description": "Country ISO code", "type": "string" } } }, "AmountEvent": { "description": "Amount of the event.", "type": "number", "format": "float" }, "Currency": { "description": "Three-letter [ISO4217](https://en.wikipedia.org/wiki/ISO_4217) code of the currency for the amount. Currently supported currency values are enumerated above.", "type": "string", "example": "EUR", "enum": [ "BGN", "BRL", "CHF", "CLP", "CZK", "DKK", "EUR", "GBP", "HRK", "HUF", "NOK", "PLN", "RON", "SEK", "USD" ] }, "EventType": { "description": "Type of the transaction event.", "type": "string", "enum": [ "PAYOUT", "CHARGE_BACK", "REFUND", "PAYOUT_DEDUCTION" ] }, "EventStatus": { "description": "Status of the transaction event.", "type": "string", "enum": [ "PENDING", "SCHEDULED", "FAILED", "REFUNDED", "SUCCESSFUL", "PAID_OUT" ] }, "EventID": { "description": "Unique ID of the transaction event.", "type": "integer", "format": "int64" }, "HorizontalAccuracy": { "description": "Indication of the precision of the geographical position received from the payment terminal.", "type": "number", "format": "float" }, "Lat": { "description": "Latitude value from the coordinates of the payment location (as received from the payment terminal reader).", "type": "number", "format": "float", "maximum": 90, "minimum": 0 }, "LinkRefund": { "allOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "object", "properties": { "min_amount": { "description": "Minimum allowed amount for the refund.", "type": "number", "format": "float" }, "max_amount": { "description": "Maximum allowed amount for the refund.", "type": "number", "format": "float" } } } ] }, "Lon": { "description": "Longitude value from the coordinates of the payment location (as received from the payment terminal reader).", "type": "number", "format": "float", "maximum": 180, "minimum": 0 }, "TransactionID": { "description": "Unique ID of the transaction.", "type": "string" }, "TimestampEvent": { "description": "Date and time of the transaction event.", "type": "string", "format": "date-time" }, "APIKey": { "description": "An API key is a static token that allows you to authorize with SumUp APIs.\nKeep your API keys secret and safe. Do not share your API keys or expose them in a publicly accessible areas such as client-side code (browser or apps) or in the GitHub.", "type": "object", "properties": { "id": { "description": "Unique identifier of the API Key.", "type": "string", "example": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU" }, "name": { "description": "User-assigned name of the API Key.", "type": "string", "example": "My API Key" }, "scopes": { "$ref": "#/components/schemas/OAuth2Scopes" }, "type": { "type": "string", "example": "secret", "enum": [ "public", "secret" ] }, "plaintext": { "description": "The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.", "type": "string", "example": "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ" }, "preview": { "description": "Last 8 characters of the API key.", "type": "string", "example": "p6cL1vyZ" }, "created_at": { "description": "The timestamp of when the API key was created.", "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { "description": "The timestamp of when the API key was last updated.", "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" } }, "required": [ "id", "name", "scopes", "preview", "type", "created_at", "updated_at" ], "title": "API Key" }, "APIKeysList": { "description": "List of API keys.", "type": "object", "properties": { "items": { "description": "List of API keys.", "type": "array", "items": { "$ref": "#/components/schemas/APIKey" } }, "total_count": { "description": "Total number of API keys.", "type": "integer" } }, "example": { "total_count": 2, "items": [ { "id": "sup_pk_1tpmgizNLHMkx1DdKd2hdzorZAaf6AcZ9", "name": "", "type": "public", "preview": "Aaf6AcZ9", "scopes": [], "created_at": "2023-03-24T10:10:10Z", "updated_at": "2023-03-24T10:10:10Z" }, { "id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU", "name": "Test Key", "type": "secret", "preview": "TGhqew1b", "scopes": [ "transactions.history", "user.app-settings", "user.profile_readonly", "user.profile", "user.subaccounts", "user.payout-settings", "products", "payments", "payment_instruments", "readers.read", "readers.write" ], "created_at": "2023-03-25T09:10:10Z", "updated_at": "2023-03-25T09:10:10Z" } ] }, "required": [ "items", "total_count" ] }, "OAuth2Scopes": { "type": "array", "items": { "type": "string", "enum": [ "accounting.read", "accounting.write", "email", "invoices.read", "invoices.write", "payment_instruments", "payments", "products", "profile", "readers.read", "readers.write", "transactions.history", "user.app-settings", "user.payout-settings", "user.profile", "user.profile_readonly", "user.subaccounts" ] }, "example": [ "invoices.read", "invoices.write", "products", "user.app-settings" ], "maxItems": 128 }, "Preauth": { "type": "object", "properties": { "hint": { "type": "string" } }, "additionalProperties": false, "required": [ "hint" ] }, "SignupContext": { "type": "object", "properties": { "client_id": { "type": "string", "example": "client-id" }, "intent": { "type": "string", "example": "invoices" } } }, "Operator": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "username": { "type": "string", "example": "operator1@mydomain.com" }, "nickname": { "type": "string", "example": "Operator 1", "nullable": true }, "disabled": { "type": "boolean", "example": false }, "created_at": { "description": "The timestamp of when the operator was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The timestamp of when the operator was last updated.", "type": "string", "format": "date-time" }, "permissions": { "$ref": "#/components/schemas/Permissions" }, "account_type": { "type": "string", "enum": [ "operator", "normal" ] } }, "required": [ "id", "username", "disabled", "created_at", "updated_at", "permissions", "account_type" ] }, "CompatError": { "description": "Error", "type": "object", "properties": { "error_code": { "type": "string", "example": "NOT_FOUND" }, "message": { "type": "string", "example": "Resource not found." } }, "required": [ "error_code", "message" ] }, "LegacyOTP": { "type": "object", "properties": { "otpToken": { "type": "string" } }, "required": [ "otpToken" ] }, "CompatIntrospectionError": { "description": "An error response from an token introspection endpoint", "type": "object", "properties": { "error_code": { "description": "An error code identifying the type of error that occurred", "type": "string" }, "error_message": { "description": "A human readable description on the error", "type": "string" } }, "example": { "error_code": "NOT_AUTHORIZED", "error_message": "invalid access token" }, "required": [ "error_code" ] }, "CompatSessionInfo": { "description": "Object containing information about a access token session.\n\nThe properties `user_id` and `merchant_id` will be set only if the token is issued for an SumUp internal OAuth 2.0 client.\n", "type": "object", "properties": { "access_token": { "description": "The provided access token.", "type": "string" }, "legacy_token": { "description": "Same value as the `access_token` field. Exists for compatibility reasons.", "type": "string" }, "merchant_code": { "description": "The merchant code of the merchant the user is currently logged in to.", "type": "string" }, "scope": { "description": "Space separated list of the scopes the token authorizes the user for", "type": "string" }, "client_id": { "description": "The client id of the client the token was issued for.", "type": "string" }, "user_id": { "description": "The user id of the user the token was issued for.", "type": "integer" }, "merchant_id": { "description": "The merchant id of the merchant the user is currently logged in to.", "type": "integer" } }, "example": { "access_token": "at_classic_tW1BQcMv14Txz4LzPsnVJqSlMYxyuj50YCEo2j3deCQTYqpsd0teZ", "legacy_token": "at_classic_tW1BQcMv14Txz4LzPsnVJqSlMYxyuj50YCEo2j3deCQTYqpsd0teZ", "merchant_code": "MCKKXS9R", "scope": "email profile", "client_id": "cc_classic_ICt5WKz28oDNgvHch6oSKAMJaIZUN" }, "required": [ "access_token", "legacy_token", "scope", "client_id" ] }, "CompatTokenRequest": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "password", "client_credentials", "urn:ietf:params:oauth:grant-type:token-exchange", "refresh_token" ], "nullable": true, "x-oapi-codegen-extra-tags": { "form": "grant_type" } }, "client_id": { "type": "string", "nullable": true, "x-oapi-codegen-extra-tags": { "form": "client_id" } }, "client_secret": { "type": "string", "nullable": true, "x-oapi-codegen-extra-tags": { "form": "client_secret" } }, "code": { "type": "string", "nullable": true, "x-oapi-codegen-extra-tags": { "form": "code" } }, "username": { "type": "string", "nullable": true, "x-oapi-codegen-extra-tags": { "form": "username" } }, "password": { "type": "string", "example": "correct horse batter staple", "nullable": true, "x-oapi-codegen-extra-tags": { "form": "password" } }, "refresh_token": { "type": "string", "nullable": true, "x-oapi-codegen-extra-tags": { "form": "refresh_token" } }, "subject_token": { "type": "string", "nullable": true, "x-oapi-codegen-extra-tags": { "form": "subject_token" } }, "subject_token_type": { "type": "string", "nullable": true, "x-oapi-codegen-extra-tags": { "form": "subject_token_type" } }, "scope": { "description": "Space separated list of requested scopes.", "type": "string", "nullable": true, "x-oapi-codegen-extra-tags": { "form": "scope" } }, "hashed": { "description": "Hashed is used by legacy applications (notably cube) to submit the password in the password flow in pre-hashed format (the password is md5 hashed on the client and submitted in such format).\n", "type": "boolean", "nullable": true, "x-oapi-codegen-extra-tags": { "form": "hashed" } } } }, "CompatToken": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "description": "The TTL of the token in seconds.", "type": "integer", "format": "int64" }, "refresh_token": { "type": "string" }, "scope": { "description": "Space separated list of scopes effective for this token.", "type": "string" }, "issued_token_type": { "type": "string" }, "account_type": { "description": "Type of the account of the user this token was issued for. Present only for internal clients in password flow.\n", "type": "string" }, "consent_reused": { "description": "Used to support the OAuth2 authorization flow handled by gateway.", "type": "boolean" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ] }, "TokenError": { "type": "object", "properties": { "error": { "description": "Identifier of the error.", "type": "string", "example": "invalid_request" }, "error_description": { "description": "Short description of the error.", "type": "string", "example": "missing client credentials" } }, "required": [ "error", "error_description" ] }, "ValidatedToken": { "type": "object", "properties": { "name": { "description": "The standardized authentication cookie name used for webviews.\n", "type": "string" }, "value": { "description": "The validated token.\n", "type": "string" } }, "required": [ "name", "value" ] }, "ClassicContext": { "description": "Ext authz agent classic context", "type": "object", "properties": { "user_id": { "type": "integer", "format": "int32" }, "merchant_code": { "type": "string", "example": "MC0X0ABC" } } }, "SignatureContext": { "description": "Ext authz agent signature context", "type": "object", "properties": { "body_digest": { "type": "string" }, "meta": { "description": "Application-specific data provided by the signer which should be used when authorizing request together with `body_digest`.", "type": "object", "x-go-type": "json.RawMessage" }, "amr": { "description": "Method used to authenticate the requester when obtaining the signature.", "type": "array", "items": { "type": "string", "enum": [ "otp", "swk", "sms", "email" ] }, "example": [ "otp" ] } } }, "AuthorizationContext": { "description": "Ext authz agent authorization context", "type": "object", "properties": { "client_id": { "type": "string" }, "scp": { "type": "array", "items": { "type": "string" } }, "ext": { "type": "object", "properties": { "classic": { "$ref": "#/components/schemas/ClassicContext" }, "sig": { "$ref": "#/components/schemas/SignatureContext" } } }, "sub": { "type": "string" }, "aud": { "type": "array", "items": { "type": "string" } } }, "required": [ "client_id", "scp" ] }, "UserInfo": { "description": "Basic account info from an user", "type": "object", "properties": { "merchant_code": { "type": "string", "example": "MC0X0ABC" }, "user_id": { "type": "integer", "format": "int32", "example": 1234 }, "merchant_id": { "type": "integer", "format": "int32", "example": 1111 } }, "example": { "merchant_code": "MC0X0ABC", "user_id": 12345678, "merchant_id": 87654321 } }, "SampleBody": { "description": "Body to be sent in the signature validation example endpoint", "type": "object", "properties": { "action_id": { "type": "string" }, "params": { "description": "Application-specific data provided by the signer which should be used when authorizing request together with `body_digest`.", "type": "object", "x-go-type": "json.RawMessage" } }, "required": [ "action_id", "params" ] }, "OTP": { "type": "object", "properties": { "otp_channel": { "$ref": "#/components/schemas/OTPChannel" }, "otp_recipient": { "description": "Masked recipient of the OTP.\n", "type": "string", "example": "+420*******898" } }, "required": [ "otp_channel", "otp_recipient" ] }, "OTPChannel": { "description": "The Out-of-Band channel for OTP delivery.", "type": "string", "default": "sms", "enum": [ "sms", "whatsapp" ] }, "DeviceRequest": { "type": "object", "properties": { "platform_device_id": { "description": "The device identifier created by the mobile app after installation on the device. This is a UUID although iOS and Android may use different versions.\n", "type": "string", "example": "B87A160D-C9B8-4A25-87B4-A59036AECE61", "maxLength": 64 }, "app_id": { "description": "client id of the app", "type": "string", "example": "ios_merchant_app", "maxLength": 64 }, "app_version": { "description": "App version of the device", "type": "string", "example": "2.59.16", "maxLength": 64 }, "name": { "description": "Human readable name of the device.", "type": "string", "example": "John's iPhone", "maxLength": 124 }, "push_token": { "description": "Push token used for sending push notifications\n", "type": "string", "example": "7a8d93b3 2b6c881a 5d71e43e 6b95a7f0 1bfe62c8 f49d5e4c d28be4b8 7ec0a941", "maxLength": 256 } }, "required": [ "name" ] }, "SignupVerificationStatus": { "type": "object", "properties": { "verified": { "description": "True if the signup email has been verified.", "type": "boolean", "example": true }, "status": { "description": "The state of the signup verification.\nPossible values are:\n* `pending` - the signup is pending confirmation\n* `verified` - the signup has been verified as can be claimed\n* `claimed` - the signup has been claimed\n", "type": "string", "example": "pending", "enum": [ "pending", "verified", "claimed" ] } }, "required": [ "verified", "status" ] }, "ValidationError": { "type": "object", "properties": { "error_code": { "type": "string", "example": "NOT_FOUND" }, "message": { "type": "string", "example": "Resource not found" }, "param": { "type": "string", "example": "group" } }, "required": [ "error_code", "message", "param" ] }, "ToSAcceptance": { "description": "Details on the acceptance of the SumUp Terms of Service Agreement", "type": "object", "properties": { "accepted_at": { "description": "The Unix timestamp marking when the user accepted Terms of Service agreement.", "type": "string", "format": "date-time", "example": "2023-03-25T09:10:10Z" }, "ip_address": { "description": "The IP address from which the user accepted Terms of Service agreement.", "type": "string", "example": "127.0.0.1" }, "user_agent": { "description": "The user agent of the browser from which the user accepted Terms of Service agreement.", "type": "string", "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:109.0) Gecko/20100101 Firefox/113.0" } }, "required": [ "accepted_at", "ip_address", "user_agent" ] }, "Zoneinfo": { "description": "String from zoneinfo time zone database representing the user's time zone.", "type": "string", "example": "Europe/Paris", "maxLength": 124, "nullable": true }, "CountryCode": { "description": "An [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2](ISO3166-1 alpha-2) country code. This definition users `oneOf` with a two-character string type to allow for support of future countries in client code.\nPossible values are: ``` - \"AT\" - \"AU\" - \"BE\" - \"BG\" - \"BR\" - \"CH\" - \"CL\" - \"CO\" - \"CY\" - \"CZ\" - \"DE\" - \"DK\" - \"EE\" - \"ES\" - \"FI\" - \"FR\" - \"GB\" - \"GR\" - \"HU\" - \"IE\" - \"IT\" - \"LT\" - \"LU\" - \"LV\" - \"MT\" - \"MX\" - \"NL\" - \"NO\" - \"PE\" - \"PL\" - \"PT\" - \"RO\" - \"SE\" - \"SI\" - \"SK\" - \"US\" ```\n", "type": "string", "example": "BR", "maxLength": 2, "minLength": 2 }, "User": { "description": "The userinfo response", "type": "object", "properties": { "id": { "description": "Identifier for the End-User (also called Subject).", "type": "string", "example": "44ca0f5b-813b-46e1-aee7-e6242010662e" }, "created_at": { "description": "Time the End-User was created.\n", "type": "string", "format": "date-time", "example": "2022-05-03T14:46:44.185202Z" }, "updated_at": { "description": "Time the End-User's information was last updated.\n", "type": "string", "format": "date-time", "example": "2022-05-03T14:46:44.185202Z" }, "blocked_at": { "description": "Time the End-User was blocked.\n", "type": "string", "format": "date-time", "example": "2022-05-03T14:46:44.185202Z" }, "email": { "description": "End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.\n", "type": "string", "example": "example@sumup.com" }, "email_verified": { "description": "True if the End-User's e-mail address has been verified; otherwise false. When this Claim Value is true, this means that the we took affirmative steps to ensure that this e-mail address was controlled by the End-User at the time the verification was performed.\n", "type": "boolean", "example": true }, "phone_number": { "description": "End-User's preferred telephone number in E.164 [E.164] format. For example, +1 (425) 555-1212 or +56 (2) 687 2400. Can be empty if the user doesn't have phone number set.", "type": "string", "example": "+55115525632555" }, "phone_number_verified": { "description": "True if the End-User's phone number has been verified; otherwise false. When this Claim Value is true, this means that we took affirmative steps to ensure that this phone number was controlled by the End-User at the time the verification was performed.\n", "type": "boolean", "example": true }, "attributes": { "description": "Any additional attributes associated with the user such as parameters present during the signup.", "type": "object" }, "locale": { "description": "End-User's locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA.\n", "type": "string", "example": "de-AT" }, "tos_acceptance": { "$ref": "#/components/schemas/ToSAcceptance" }, "marketing_consent": { "description": "True if the user has given consent to marketing communication.\n**This is only valid on user creation. Identity does not store or track the consent over time, should the user for example choose to revoke.**\n", "type": "boolean", "example": true, "readOnly": true }, "zoneinfo": { "$ref": "#/components/schemas/Zoneinfo" }, "name": { "description": "End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences.", "type": "string", "example": "Anna Maria Sophie Müller" }, "nickname": { "description": "Casual name of the End-User that may or may not be the same as the given_name. For instance, a nickname value of Mike might be returned alongside a given_name value of Michael.", "type": "string", "example": "An" }, "given_name": { "description": "Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.", "type": "string", "example": "Anna" }, "middle_name": { "description": "Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.", "type": "string", "example": "Maria Sophie" }, "family_name": { "description": "Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.", "type": "string", "example": "Müller" }, "gender": { "description": "End-User's gender. Values defined by this specification are female and male. Other values MAY be used when neither of the defined values are applicable.", "type": "string", "example": "female" }, "birthdate": { "description": "End-User's birthday, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format.", "type": "string", "format": "date-time" }, "address": { "$ref": "#/components/schemas/Address" }, "mfa_on_login_enabled": { "description": "True if the End-User's wants to enabled MFA on login, false otherwise.\n", "type": "boolean", "example": true }, "mfa_disabled": { "description": "True if the End-User's wants to disable MFA completely, false otherwise.\n", "type": "boolean", "example": true }, "password_updated_at": { "description": "Time the End-User's password was last updated.\n", "type": "string", "format": "date-time", "example": "2022-05-03T14:46:44.185202Z" }, "picture": { "description": "URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.\n", "type": "string", "format": "uri", "example": "https://usercontent.sumup.com/u/44ca0f5b-813b-46e1-aee7-e6242010662e.png" }, "is_virtual": { "description": "Indicates whether a user is a managed user. Managed users are team members for which the owner of the merchant has set the password. These users have not gone through an invitation flow and cannot own merchants of their own or be invited to other merchants.\n", "type": "boolean", "example": false }, "is_service_account": { "description": "Indicates whether a user is a service account.\n", "type": "boolean", "example": false }, "feature_previews": { "description": "Experimental features that the user has enabled for themselves.\n", "type": "object", "example": { "passkeys": true, "dark_mode": true }, "additionalProperties": { "type": "boolean" } }, "color_scheme_preference": { "description": "User's preference for the color scheme.\n", "type": "string", "example": "system", "enum": [ "light", "dark", "system" ] } }, "required": [ "id", "email", "email_verified", "created_at", "updated_at", "phone_number", "phone_number_verified", "is_virtual", "marketing_consent", "mfa_on_login_enabled", "mfa_disabled" ] }, "Device": { "type": "object", "properties": { "id": { "description": "Unique identifier for the device. The ID is generated on the backend on device creation. It is not to be confused with the `platform_device_id`.\n", "type": "string", "example": "55E996A4-7F5E-44C2-B29A-869DE8A82A8A", "maxLength": 64 }, "platform_device_id": { "description": "The device identifier created by the mobile app after installation on the device. This is a UUID although iOS and Android may use different versions.\n", "type": "string", "example": "B87A160D-C9B8-4A25-87B4-A59036AECE61", "maxLength": 64 }, "app_id": { "description": "The client application's identifier.", "type": "string", "example": "ios_merchant_app" }, "app_version": { "description": "The client application's reported version. Not to confuse with the device operating system version.", "type": "string" }, "name": { "description": "A human readable name for the device. In case of mobile phone's, it may be a name recognizable to the owner of the device.", "type": "string" }, "push_token": { "description": "Push token used for sending push notifications\n", "type": "string", "example": "7a8d93b3 2b6c881a 5d71e43e 6b95a7f0 1bfe62c8 f49d5e4c d28be4b8 7ec0a941" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name" ], "title": "Device" }, "MembershipStatus": { "description": "The status of the membership.", "type": "string", "enum": [ "accepted", "pending", "expired", "disabled", "unknown" ] }, "Membership": { "description": "A membership associates a user with a resource, memberships is defined by user, resource, resource type, and associated roles.", "type": "object", "properties": { "id": { "description": "ID of the membership.", "type": "string", "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" }, "resource_id": { "description": "ID of the resource the membership is in.", "type": "string", "example": "M2DDT39A" }, "type": { "description": "Type of the resource the membership is in.", "type": "string", "example": "merchant", "enum": [ "merchant" ] }, "roles": { "description": "User's roles.", "type": "array", "items": { "type": "string" }, "example": [ "role_admin" ] }, "permissions": { "description": "User's permissions.", "type": "array", "items": { "type": "string" }, "example": [ "members_read", "members_write", "create_moto_payments", "full_transaction_history_view", "refund_transactions", "create_referral", "developer_settings_edit", "developer_settings_access" ] }, "created_at": { "description": "The timestamp of when the membership was created.", "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { "description": "The timestamp of when the membership was last updated.", "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "invite": { "$ref": "#/components/schemas/Invite" }, "status": { "$ref": "#/components/schemas/MembershipStatus" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "attributes": { "$ref": "#/components/schemas/Attributes" }, "resource": { "$ref": "#/components/schemas/MembershipResource" } }, "required": [ "id", "resource_id", "type", "roles", "permissions", "created_at", "updated_at", "status", "resource" ], "title": "Membership" }, "MembershipResource": { "description": "Information about the resource the membership is in.", "type": "object", "properties": { "id": { "description": "ID of the resource the membership is in.", "type": "string", "example": "M2DDT39A" }, "type": { "type": "string", "example": "merchant", "enum": [ "merchant" ], "additionalProperties": { "type": "string" } }, "name": { "description": "Display name of the resource.", "type": "string", "example": "Acme Corp" }, "logo": { "description": "Logo fo the resource.", "type": "string", "format": "uri", "example": "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png", "maxLength": 256, "x-go-type": "apitypes.URI", "x-go-type-import": { "path": "github.com/sumup/x/apitypes" } }, "created_at": { "description": "The timestamp of when the membership resource was created.", "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { "description": "The timestamp of when the membership resource was last updated.", "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "attributes": { "$ref": "#/components/schemas/Attributes" } }, "required": [ "id", "type", "name", "created_at", "updated_at", "attributes" ], "title": "Resource" }, "Member": { "description": "A member is user within specific resource identified by resource id, resource type, and associated roles.", "type": "object", "properties": { "id": { "description": "ID of the member.", "type": "string", "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" }, "roles": { "description": "User's roles.", "type": "array", "items": { "type": "string" }, "example": [ "role_admin" ] }, "permissions": { "description": "User's permissions.", "type": "array", "items": { "type": "string" }, "example": [ "members_read", "members_write", "create_moto_payments", "full_transaction_history_view", "refund_transactions", "create_referral", "developer_settings_edit", "developer_settings_access" ] }, "created_at": { "description": "The timestamp of when the member was created.", "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { "description": "The timestamp of when the member was last updated.", "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "user": { "$ref": "#/components/schemas/MembershipUser" }, "invite": { "$ref": "#/components/schemas/Invite" }, "status": { "$ref": "#/components/schemas/MembershipStatus" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "attributes": { "$ref": "#/components/schemas/Attributes" } }, "example": { "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", "roles": [ "role_admin", "role_owner" ], "permissions": [ "members_read", "members_write", "create_moto_payments", "full_transaction_history_view", "refund_transactions", "create_referral", "developer_settings_edit", "developer_settings_access" ], "created_at": "2023-01-20T15:16:17Z", "updated_at": "2023-02-20T15:16:17Z", "user": { "id": "44ca0f5b-813b-46e1-aee7-e6242010662e", "email": "example@sumup.com", "mfa_on_login_enabled": true, "virtual_user": false, "service_account_user": false }, "status": "accepted" }, "required": [ "id", "roles", "permissions", "created_at", "updated_at", "status" ], "title": "Member" }, "Invite": { "description": "Pending invitation for membership.", "type": "object", "properties": { "email": { "description": "Email address of the invited user.", "type": "string", "format": "email", "example": "boaty.mcboatface@sumup.com" }, "expires_at": { "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" } }, "required": [ "email", "expires_at" ], "title": "Invite" }, "MembershipUser": { "description": "Information about the user associated with the membership.", "type": "object", "properties": { "id": { "description": "Identifier for the End-User (also called Subject).", "type": "string", "example": "44ca0f5b-813b-46e1-aee7-e6242010662e" }, "email": { "description": "End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.", "type": "string", "example": "example@sumup.com" }, "mfa_on_login_enabled": { "description": "True if the user has enabled MFA on login.", "type": "boolean", "example": true }, "virtual_user": { "description": "True if the user is a virtual user (operator).", "type": "boolean", "example": false }, "service_account_user": { "description": "True if the user is a service account.", "type": "boolean", "example": false }, "disabled_at": { "description": "Time when the user has been disabled. Applies only to virtual users (`virtual_user: true`).", "type": "string", "format": "date-time" }, "nickname": { "description": "User's preferred name. Used for display purposes only.", "type": "string", "example": "Test User" }, "picture": { "description": "URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.", "type": "string", "format": "uri", "example": "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png" }, "classic": { "$ref": "#/components/schemas/MembershipUserClassic" } }, "required": [ "id", "email", "mfa_on_login_enabled", "virtual_user", "service_account_user" ] }, "MembershipUserClassic": { "description": "Classic identifiers of the user.", "type": "object", "properties": { "user_id": { "type": "integer", "format": "int32" } }, "deprecated": true, "required": [ "user_id" ] }, "Role": { "description": "A custom role that can be used to assign set of permissions to members.", "type": "object", "properties": { "id": { "description": "Unique identifier of the role.", "type": "string", "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", "x-go-type": "memberships.RoleIDOrSlug", "x-go-type-import": { "path": "github.com/sumup/identity/apps/portier-backend/internal/domain/memberships" } }, "name": { "description": "User-defined name of the role.", "type": "string", "example": "Senior Shop Manager II" }, "description": { "description": "User-defined description of the role.", "type": "string", "example": "Manges the shop and the employees." }, "permissions": { "description": "List of permission granted by this role.", "type": "array", "items": { "type": "string" }, "example": [ "members_list", "members_read", "members_view", "members_write", "members_delete" ], "maxItems": 100 }, "is_predefined": { "description": "True if the role is provided by SumUp.", "type": "boolean", "example": true }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "created_at": { "description": "The timestamp of when the role was created.", "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { "description": "The timestamp of when the role was last updated.", "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" } }, "required": [ "id", "name", "permissions", "is_predefined", "created_at", "updated_at" ] }, "Metadata": { "description": "Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.", "type": "object", "example": {}, "additionalProperties": { "maxLength": 256 } }, "Attributes": { "description": "Object attributes that modifiable only by SumUp applications.", "type": "object", "example": {}, "additionalProperties": { "maxLength": 256 } }, "Reader": { "description": "A physical card reader device that can accept in-person payments.", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ReaderID" }, "name": { "$ref": "#/components/schemas/ReaderName" }, "status": { "$ref": "#/components/schemas/ReaderStatus" }, "device": { "$ref": "#/components/schemas/ReaderDevice" }, "meta": { "$ref": "#/components/schemas/Meta" }, "created_at": { "description": "The timestamp of when the reader was created.", "type": "string", "format": "date-time", "example": "2023-01-18T15:16:17Z" }, "updated_at": { "description": "The timestamp of when the reader was last updated.", "type": "string", "format": "date-time", "example": "2023-01-20T15:16:17Z" } }, "required": [ "id", "name", "status", "device", "created_at", "updated_at" ], "title": "Reader" }, "ReaderID": { "description": "Unique identifier of the object.\nNote that this identifies the instance of the physical devices pairing with your SumUp account.\nIf you DELETE a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.", "type": "string", "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "maxLength": 30, "minLength": 30, "x-go-type": "readers.ReaderID", "x-go-type-import": { "path": "github.com/sumup/identity/apps/portier-backend/internal/domain/readers" } }, "ReaderName": { "description": "Custom human-readable, user-defined name for easier identification of the reader.", "type": "string", "example": "Frontdesk", "maxLength": 500 }, "ReaderStatus": { "description": "The status of the reader object gives information about the current state of the reader.\n\nPossible values:\n\n- `unknown` - The reader status is unknown.\n- `processing` - The reader is created and waits for the physical device to confirm the pairing.\n- `paired` - The reader is paired with a merchant account and can be used with SumUp APIs.\n- `expired` - The pairing is expired and no longer usable with the account. The resource needs to get recreated", "type": "string", "example": "paired", "enum": [ "unknown", "processing", "paired", "expired" ] }, "ReaderDevice": { "description": "Information about the underlying physical device.\n", "type": "object", "properties": { "identifier": { "description": "A unique identifier of the physical device (e.g. serial number).", "type": "string", "example": "U1DT3NA00-CN" }, "model": { "description": "Identifier of the model of the device.", "type": "string", "example": "solo", "enum": [ "solo", "virtual-solo" ] } }, "required": [ "identifier", "model" ] }, "ReaderPairingCode": { "description": "The pairing code is a 8 or 9 character alphanumeric string that is displayed on a SumUp Device after initiating the pairing. It is used to link the physical device to the created pairing.", "type": "string", "example": "4WLFDSBF", "maxLength": 9, "minLength": 8 }, "Meta": { "description": "Set of user-defined key-value pairs attached to the object.", "type": "object", "example": {}, "additionalProperties": { "maxLength": 256 }, "maxProperties": 50 }, "AddressResponse": { "description": "Personal address information.", "type": "object", "properties": { "city": { "description": "City name from the address.", "type": "string", "example": "Berlin" }, "country": { "description": "Two letter country code formatted according to [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "example": "DE" }, "line1": { "description": "First line of the address with details of the street name and number.", "type": "string", "example": "Sample street" }, "line2": { "description": "Second line of the address with details of the building, unit, apartment, and floor numbers.", "type": "string", "example": "ap. 5" }, "postal_code": { "description": "Postal code from the address.", "type": "string", "example": "10115" }, "state": { "description": "State name or abbreviation from the address.", "type": "string", "example": "Berlin" } } } }, "examples": { "CreatedReader": { "summary": "A reader that waits for the physical device to acknowledge the pairing.", "value": { "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", "name": "Frontdesk", "status": "processing", "device": { "identifier": "U1DT3NA00-CN", "model": "solo" }, "created_at": "2023-05-09T14:50:20.214Z", "updated_at": "2023-05-09T14:52:58.714Z" } } }, "links": { "UpdateReaderByID": { "operationId": "UpdateReader", "parameters": { "id": "$response.body#/id" }, "description": "Update the reader object. This can be used to set a name after using this endpoint to verify the pairing code.\n" }, "DeleteReaderByID": { "operationId": "DeleteReader", "parameters": { "id": "$response.body#/id" }, "description": "Delete the reader.\n" } }, "requestBodies": { "BankAccounts": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountPayload" } } } }, "CheckoutCreate": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCreateRequest" }, "examples": { "Checkout": { "description": "Standard request body for creating a checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MDUDGLR9", "description": "Purchase", "id": "2b79757a-de87-4a2e-90e4-b17c947c730d", "status": "PAID", "date": "2020-02-29T10:56:56+00:00", "merchant_name": "John Doe LTD", "redirect_url": "https://sumup.com" } }, "Checkout3DS": { "description": "Create a 3DS checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MH4H92C7", "description": "Purchase", "return_url": "http://example.com/", "customer_id": "831ff8d4cd5958ab5670", "redirect_url": "https://mysite.com/completed_purchase" } }, "CheckoutAPM": { "description": "Create an Alternative Payment Method checkout", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "merchant_code": "MH4H92C7", "redirect_url": "https://mysite.com/completed_purchase" } } } } } }, "CheckoutProcess": { "description": "Details of the payment instrument for processing the checkout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutProcessMixin" }, "examples": { "ProcessCard": { "description": "Process a checkout with a card", "value": { "payment_type": "card", "installments": 1, "mandate": { "type": "recurrent", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36", "user_ip": "172.217.169.174" }, "card": { "type": "VISA", "name": "John Doe", "number": "1234567890123456", "expiry_year": "2023", "expiry_month": "01", "cvv": "123", "zip_code": "12345", "last_4_digits": "3456" } } }, "ProcessToken": { "description": "Process a checkout with a token", "value": { "payment_type": "card", "installments": 1, "token": "ba85dfee-c3cf-48a6-84f5-d7d761fbba50", "customer_id": "MEDKHDTI" } }, "ProcessBoleto": { "description": "Process a checkout with Boleto", "value": { "payment_type": "boleto", "personal_details": { "email": "user@example.com", "first_name": "John", "last_name": "Doe", "tax_id": "423.378.593-47", "address": { "country": "BR", "city": "São Paulo", "line1": "Rua Gilberto Sabino, 215", "state": "SP", "postal_code": "05425-020" } } } }, "ProcessiDeal": { "description": "Process a checkout with iDeal", "value": { "payment_type": "ideal", "personal_details": { "email": "user@example.com", "first_name": "John", "last_name": "Doe", "address": { "country": "NL" } } } }, "ProcessBancontact": { "description": "Process a checkout with Bancontact", "value": { "payment_type": "bancontact", "personal_details": { "email": "user@example.com", "first_name": "John", "last_name": "Doe", "address": { "country": "BE" } } } } } } } }, "CustomerCreate": { "description": "Details of the customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "CustomerUpdate": { "content": { "application/json": { "schema": { "type": "object", "properties": { "personal_details": { "$ref": "#/components/schemas/PersonalDetails" } } } } } }, "DoingBusinessAs": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DoingBusinessAsPayload" } } } }, "MerchantProfile": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantProfilePayload" } } } }, "MerchantSettings": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantSettingsPayload" } } } }, "PaymentInstrument": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentInstrumentCard" } } } }, "PersonalProfile": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalProfilePayload" } } } }, "Refund": { "content": { "application/json": { "schema": { "description": "Optional amount for partial refunds of transactions.", "type": "object", "properties": { "amount": { "description": "Amount to be refunded. Eligible amount can't exceed the amount of the transaction and varies based on country and currency. If you do not specify a value, the system performs a full refund of the transaction.", "type": "number", "format": "float" } } } } } } }, "responses": { "BankAccounts": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccount" } } } } }, "Checkout": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" }, "examples": { "Checkout": { "description": "Standard response body for a successfully created checkout", "value": { "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MCNPLE22", "merchant_country": "DE", "description": "My Checkout", "return_url": "http://example.com", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2020-02-29T10:56:56+00:00", "customer_id": "831ff8d4cd5958ab5670", "mandate": { "type": "recurrent", "status": "active", "merchant_code": "MDASYTPD" }, "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345", "internal_id": 0 } ] } }, "Checkout3DS": { "description": "Response body for a successfully created 3DS checkout", "value": { "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "description": "My Checkout", "return_url": "http://example.com", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2020-02-29T10:56:56+00:00", "customer_id": "831ff8d4cd5958ab5670", "redirect_url": "https://mysite.com/completed_purchase", "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345", "internal_id": 0 } ] } }, "CheckoutAPM": { "description": "Response body for APMs, including Blik, iDeal, ...", "value": { "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MCNPLE22", "description": "My Checkout", "return_url": "http://example.com", "id": "88fcf8de-304d-4820-8f1c-ec880290eb92", "status": "PENDING", "date": "2021-06-29T11:08:36.000+00:00", "merchant_name": "My company", "merchant_country": "DE", "redirect_url": "https://sumup.com", "purpose": "CHECKOUT", "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "012345", "internal_id": 0 } ] } } } } } }, "CheckoutList": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSuccess" } } } } }, "CheckoutRetrieve": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSuccess" } } } }, "CheckoutCreate": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCreateRequest" } } } }, "CheckoutProcess": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSuccess" }, "examples": { "CheckoutSuccessCard": { "description": "Successfully processed checkout with a card", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MH4H92C7", "description": "Purchase", "return_url": "http://example.com", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "valid_until": "2020-02-29T10:56:56+00:00", "customer_id": "831ff8d4cd5958ab5670", "mandate": { "type": "recurrent", "status": "active", "merchant_code": "MDASYTPD" }, "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "053201", "internal_id": 1763892018 } ], "transaction_code": "TEENSK4W2K", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4" } }, "CheckoutSuccessToken": { "description": "Successfully processed checkout with a token", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "EUR", "pay_to_email": "user@example.com", "merchant_code": "MH4H92C7", "description": "Purchase with token", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PENDING", "date": "2020-02-29T10:56:56+00:00", "transaction_code": "TEENSK4W2K", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "merchant_name": "Sample Merchant", "redirect_url": "https://mysite.com/completed_purchase", "customer_id": "831ff8d4cd5958ab5670", "payment_instrument": { "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc" }, "transactions": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", "transaction_code": "TEENSK4W2K", "amount": 10.1, "currency": "EUR", "timestamp": "2020-02-29T10:56:56.876Z", "status": "SUCCESSFUL", "payment_type": "ECOM", "installments_count": 1, "merchant_code": "MH4H92C7", "vat_amount": 6, "tip_amount": 3, "entry_mode": "CUSTOMER_ENTRY", "auth_code": "053201", "internal_id": 1763892018 } ] } }, "CheckoutSuccessBoleto": { "description": "Successfully processed checkout with Boleto", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, "currency": "BRL", "pay_to_email": "user@example.com", "merchant_code": "MH4H92C7", "description": "Boleto checkout", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", "status": "PENDING", "date": "2021-07-06T12:34:02.000+00:00", "merchant_name": "Sample shop", "boleto": { "barcode": "34191090081790614310603072340007886840000000200", "url": "https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto" }, "redirect_url": "https://website.com", "purpose": "CHECKOUT", "transactions": [ { "id": "debd2986-9852-4e86-8a8e-7ea9c87dd679", "transaction_code": "TEN3E696NP", "merchant_code": "MH4H92C9", "amount": 10.1, "vat_amount": 6, "tip_amount": 3, "currency": "BRL", "timestamp": "2021-07-06T12:34:16.460+00:00", "status": "PENDING", "payment_type": "BOLETO", "entry_mode": "BOLETO", "installments_count": 1, "internal_id": 1763892018 } ] } }, "CheckoutSuccessiDeal": { "description": "Successfully processed checkout with iDeal", "value": { "next_step": { "url": "https://r3.girogate.de/ti/simideal", "method": "GET", "payload": { "tx": "961473700", "rs": "ILnaUeQTKJ184fVrjGILrLjePX9E4rmz", "cs": "c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5" }, "full": "https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5", "mechanism": [ "browser" ] } } }, "CheckoutSuccessBancontact": { "description": "Successfully processed checkout with Bancontact", "value": { "next_step": { "url": "https://r3.girogate.de/ti/simbcmc", "method": "GET", "payload": { "tx": "624788471", "rs": "5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB", "cs": "697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc" }, "full": "https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc", "mechanism": [ "browser" ] } } } } } } }, "CheckoutProcessAccepted": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAccepted" } } } }, "Customer": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "CustomerCreate": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "PaymentInstrumentList": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentInstrumentResponse" } } } } }, "PaymentInstrument": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentInstrumentCard" } } } }, "PaymentInstrumentCreate": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentInstrumentResponse" } } } }, "PersonalProfile": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalProfile" } } } }, "Transaction": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionFull" } } } }, "NoBodyResponse": { "description": "No Content", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "NoBody": { "value": {} } } } } }, "ErrorBadRequest": { "description": "No Content", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "NoBody": { "value": {} } } } } }, "ErrorNotAuthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid_Token": { "description": "The access token is invalid or has expired.", "value": { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } }, "Not_Authorized_Token": { "description": "The access token is valid but the application is not authorized.", "value": { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } }, "Missing_Token": { "description": "No access token is provided.", "value": { "message": "access token required", "error_code": "NOT_AUTHORIZED" } } } } } }, "ErrorForbidden": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "examples": { "Forbidden": { "description": "You do not have required scopes for making this request.", "value": { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": "403" } } } } } }, "ErrorNotFound": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not_Found": { "description": "The identified resource is not found on the server.", "value": { "error_code": "NOT_FOUND", "message": "Resource not found" } } } } } }, "ErrorConflict": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Checkout_Processed": { "description": "The identified checkout resource is already processed.", "value": { "error_code": "CHECKOUT_PROCESSED", "message": "Checkout is already processed" } } } } } }, "CompatErrorResponse": { "description": "error response for compat API calls", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatError" } } } }, "ListMemberships": { "description": "Returns a list of Membership objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Membership" } }, "total_count": { "type": "integer", "example": 3 } }, "required": [ "total_count", "items" ] } } } }, "ListMembers": { "description": "Returns a list of Member objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "total_count": { "type": "integer", "example": 3 } }, "required": [ "items" ] } } } }, "ListRoles": { "description": "Returns a list of Role objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } }, "required": [ "items" ] } } } } }, "securitySchemes": { "apiKey": { "description": "API keys allow you easily interact with SumUp APIs. API keys are static tokens. You can create API keys from the [Dashboard](https://me.sumup.com/settings/api-keys)\n", "type": "http", "scheme": "Bearer" }, "oauth2": { "type": "oauth2", "description": "SumUp supports [OAuth 2.0](https://tools.ietf.org/html/rfc6749) authentication for platforms that want to offer their services to SumUp users.\n\nTo integrate via OAuth 2.0 you will need a client credentials that you can create in the [SumUp Dashboard](https://me.sumup.com/settings/oauth2-applications).\n\nTo maintain security of our users, we highly recommend that you use one of the [recommended OAuth 2.0 libraries](https://oauth.net/code/) for authentication.\n", "flows": { "authorizationCode": { "authorizationUrl": "https://api.sumup.com/authorize", "tokenUrl": "https://api.sumup.com/token", "refreshUrl": "https://api.sumup.com/token", "scopes": { "payments": "Make payments by creating and processing checkouts.", "transactions.history": "View transactions and transaction history.", "user.profile_readonly": "View user profile details.", "user.profile": "View and manage your user profile.", "user.app-settings": "View and manage the SumUp mobile application settings.", "payment_instruments": "Manage customers and their payment instruments.", "user.payout-settings": "View and manage your payout settings.", "user.subaccounts": "View and manage the user profile details of your employees." } }, "clientCredentials": { "tokenUrl": "https://api.sumup.com/token", "scopes": { "payments": "Make payments by creating and processing checkouts.", "transactions.history": "View transactions and transaction history.", "user.profile_readonly": "View user profile details.", "user.profile": "View and manage your user profile.", "user.app-settings": "View and manage the SumUp mobile application settings.", "payment_instruments": "Manage customers and their payment instruments.", "user.payout-settings": "View and manage your payout settings.", "user.subaccounts": "View and manage the user profile details of your employee." } } } } } }, "tags": [ { "name": "Checkouts", "description": "Accept payments from your end users by adding the Checkouts model to your platform.\nSumUp supports standard and single payment 3DS checkout flows.\n\nThe Checkout model allows creating, listing, retrieving, processing and deactivating checkouts.\nA payment is completed by creating a checkout and then processing the checkout.\n", "x-core-objects": [ { "$ref": "#/components/schemas/Checkout" } ] }, { "name": "Customers", "description": "Allow your regular customers to save their information with the Customers model.\nThis will prevent re-entering payment instrument information for recurring payments on your platform.\n\nDepending on the needs you can allow, creating, listing or deactivating payment instruments & creating, retrieving and updating customers.\n", "x-core-objects": [ { "$ref": "#/components/schemas/Customer" } ] }, { "name": "Transactions", "description": "Retrieve details for a specific transaction by it’s `id`\nor any other required query parameter, or list all transactions related to the merchant account.\n" }, { "name": "Payouts", "description": "The Payouts model will allow you to track funds you’ve received from SumUp.\nYou can receive a detailed payouts list with information like dates, fees, references and statuses, using the `List payouts` endpoint.\n", "x-core-objects": [ { "$ref": "#/components/schemas/FinancialPayouts" } ] }, { "name": "Receipts", "description": "The Receipts model obtains receipt-like details for specific transactions.", "x-core-objects": [ { "$ref": "#/components/schemas/Receipt" } ] }, { "name": "Merchant", "description": "Manage merchant profile.", "x-core-objects": [ { "$ref": "#/components/schemas/MerchantAccount" } ] }, { "name": "API Keys", "description": "API Keys allow your application to gain programmatic access to SumUp.\nAPI Keys allow application to do authorized requests within the SumUp ecosystem. API Keys are scopes to single account and thus can't be used for endpoints where user presence is needed (for such endpoints it is necessary to use OAuth2).", "externalDocs": { "description": "Authentication guide", "url": "https://developer.sumup.com/api/authentication" }, "x-core-objects": [ { "$ref": "#/components/schemas/APIKey" } ] }, { "name": "Subaccounts", "description": "Endpoints for managing merchant sub-accounts (operators).", "x-deprecation-notice": "Subaccounts API is deprecated, please use [Members](https://developer.sumup.com/api/members) API instead to manage your account members.", "x-core-objects": [ { "$ref": "#/components/schemas/Operator" } ] }, { "name": "Members", "description": "Endpoints to manage account members. Members are users that have membership within merchant accounts.", "x-core-objects": [ { "$ref": "#/components/schemas/Member" } ], "x-beta": true }, { "name": "Memberships", "description": "Endpoints to manage user's memberships. Memberships are used to connect the user to merchant accounts and to grant them access to the merchant's resources via roles.", "x-core-objects": [ { "$ref": "#/components/schemas/Membership" } ], "x-beta": true }, { "name": "Roles", "description": "Endpoints to manage custom roles. Custom roles allow you to tailor roles from individual permissions to match your needs. Once created, you can assign your custom roles to your merchant account members using the memberships.", "x-core-objects": [ { "$ref": "#/components/schemas/Role" } ], "x-beta": true }, { "name": "Readers", "description": "A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments.\n", "x-core-objects": [ { "$ref": "#/components/schemas/Reader" } ], "x-beta": true } ] }