> ## Documentation Index > Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt > Use this file to discover all available pages before exploring further. # Get payments > Retrieves a paginated list of payments associated with the account. Payments are sorted in reverse chronological order (most recent first). The caller can specify the number of payments per page using a query parameter, with a maximum limit of 500 payments per page. If no value is provided, a default number of payments per page will be used. ## OpenAPI ````yaml /products/commerce/v2/openapi.yaml get /payments openapi: 3.1.0 info: title: Commerce API version: '2.0' description: > The Commerce V2 API provides a comprehensive payment orchestration platform designed to streamline and optimize payment processing for modern businesses. Built with flexibility and security at its core, our API enables you to process payments, manage authentications, and handle cardholder data across multiple payment processors without vendor lock-in. contact: name: Starfish GmbH & Co. KG email: hello@starfish.team url: https://hellgate.io/cpa/commerce license: name: Commerce API Terms url: https://hellgate.io/terms-and-conditions servers: - url: https://sandbox.hellgate.io description: Commerce SaaS Sandbox - url: https://api.hellgate.io description: Commerce SaaS Production security: [] tags: - name: payments_ci description: >- Handle payment processing where the customer is actively present and authorizing the transaction. - name: payments_mi description: >- Process transactions without direct customer interaction at the time of payment. - name: payments_modifications description: >- Modify existing payment transactions after initial authorization (capture, void, refund). - name: payments_data description: >- Access comprehensive payment transaction data for reporting, reconciliation, and analysis. - name: refunds_data description: Access detailed refund transaction data for tracking and reconciliation. - name: authentications_ci description: >- Process EMVCo 3-D Secure authentication requests as standalone transactions (one-off, recurring, installment). - name: authentications_mi description: >- Process requestor-initiated EMVCo 3-D Secure authentication requests (3RI) as standalone transactions. - name: authentications_data description: Access the results of prior authentications for reference. - name: credentials_management description: >- Manage stored payment credentials for repeat customers across all operating models. - name: tokens_create description: >- Create and import Commerce tokens to securely store cardholder data while maintaining PCI DSS compliance. - name: tokens_management description: Manage stored Commerce tokens including CVC2 security code management. - name: compliance_service description: >- Safely handle sensitive cardholder data while maintaining PCI DSS compliance via a secure proxy service. - name: network_tokens description: >- Manage network tokens with major card schemes with automatic lifecycle management. - name: merchants description: >- Configure and manage merchant accounts based on your chosen operating model. - name: reconciliation description: Reconcile imported token data. - name: processor_backup description: >- Migrate payment tokens from third-party processors (currently supports stripe.com). paths: /payments: get: tags: - payments_data summary: Get payments description: > Retrieves a paginated list of payments associated with the account. Payments are sorted in reverse chronological order (most recent first). The caller can specify the number of payments per page using a query parameter, with a maximum limit of 500 payments per page. If no value is provided, a default number of payments per page will be used. operationId: list_payments parameters: - in: query name: limit description: The desired amount of records per page. schema: type: integer minimum: 1 default: 50 maximum: 500 required: false - in: query name: page description: The desired number of the page to return. schema: type: integer minimum: 1 required: false - in: query name: from description: Return only payments created from this date. schema: type: string format: YYYY-MM-DD required: false - in: query name: to description: Return only payments created up to this date. schema: type: string format: YYYY-MM-DD required: false - in: query name: currency_code description: | Return only payments with the specified currencies. Currencies are in ISO 4217 and use a list formats, e.g.: - `currency_code=EUR` - `currency_code=EUR,USD` schema: type: string required: false - in: query name: status description: | Return only payments with the specified status. Status are given as a list, e.g.: - `status=authorized` - `status=authorized,captured`. schema: type: string required: false responses: '200': description: Success response content: application/json: schema: $ref: '#/components/schemas/PaymentResponseList' example: data: - id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8 amount: requested: 1000 authorized: 1000 created_at: '2023-10-10T00:00:00Z' currency_code: EUR flow_matrix_rule: e-commerce flow reference: 'Order #12345' status: authorized source: type: card cardholder_name: Bob Holder expiry_month: 12 expiry_year: 2030 masked_account_number: 424242XXXXXX4242 pan_type: FPAN use_case: ONE_OFF pagination: current_page: 1 page_size: 50 total_items: 1 total_pages: 1 '401': $ref: '#/components/responses/401_UnauthorizedError' '403': $ref: '#/components/responses/403_ForbiddenError' '422': $ref: '#/components/responses/422_ValidationError' security: - APIKeyAuth: [] components: schemas: PaymentResponseList: type: object properties: data: type: array items: $ref: '#/components/schemas/PaymentResponse' pagination: $ref: '#/components/schemas/Pagination' PaymentResponse: type: object properties: id: type: string format: uuid description: The ID of the payment on Commerce action_requirement: $ref: '#/components/schemas/ActionRequirement' additional_information: $ref: '#/components/schemas/AdditionalInformation' authentication_preference: $ref: '#/components/schemas/AuthenticationPreference' authentication_result: $ref: '#/components/schemas/AuthenticationResult' amount: type: object properties: requested: $ref: '#/components/schemas/Amount' authorized: $ref: '#/components/schemas/Amount' captured: $ref: '#/components/schemas/Amount' voided: $ref: '#/components/schemas/Amount' refunded: $ref: '#/components/schemas/Amount' created_at: type: string description: The date-time the payment was created (following ISO 8601) format: date-time currency_code: $ref: '#/components/schemas/CurrencyCode' credential_id: type: string format: uuid description: The ID of the credential associated with the payment. failure_details: type: array description: > The reasons why a payment failed during processing in Commerce. This can be due to processing errors on the side of the processor, as well as errors in the processing of the underlying flow. In case the failure is due to a processing problem, the transaction history of the payment can give more information on the exact failure details. items: type: object properties: classifier: type: string message: type: string source: type: string enum: - processor - integration - protocol flow_matrix_rule: type: string description: > The rule in the flow matrix, which was chosen to process the payment. initial_payment_id: type: string format: uuid description: | The ID of the initial payment. Only present for subsequent merchant-initiated payments. processing_annotations: type: object description: > This is an optional attribute holding results from eventual pre-processing of the request. reference: $ref: '#/components/schemas/PaymentReference' recurring_expiry: type: string format: yyyyMMdd description: | The date when the recurring should expiry. Only present for recurring payments. recurring_frequency: type: integer description: | Indicates the minimum number of days between authorisations. Only present for recurring payments. source: $ref: '#/components/schemas/PaymentSource' splits: $ref: '#/components/schemas/PaymentSplitsResponse' status: $ref: '#/components/schemas/PaymentStatus' use_case: $ref: '#/components/schemas/UseCase' metadata: $ref: '#/components/schemas/Metadata' required: - id - amount - created_at - currency_code - reference - status - use_case Pagination: type: object description: > The meta-data describing lists of data from the Commerce API. The pages are indexed from 1 up to the total_pages. properties: current_page: type: integer description: The index of the current page page_size: type: integer description: > The maximum number of items on a page (relates to the limit query parameter) total_items: type: integer description: The total quantity of items regardless of the pages total_pages: type: integer description: The total amount of pages the data is segmented into example: current_page: 1 page_size: 1 total_items: 1 total_pages: 1 ErrorGeneric: type: object properties: code: $ref: '#/components/schemas/ErrorStatusCode' classifier: $ref: '#/components/schemas/ErrorClassifier' message: $ref: '#/components/schemas/ErrorMessage' ErrorValidation: type: object properties: code: $ref: '#/components/schemas/ErrorStatusCode' classifier: $ref: '#/components/schemas/ErrorClassifier' message: $ref: '#/components/schemas/ErrorMessage' validation_errors: type: array items: type: object properties: path: type: string description: Json-path in the request which points to the validation error message: type: string description: Human readable validation message ActionRequirement: type: object properties: type: type: string enum: - use_sdk session_id: type: string format: uuid description: The id of the session to use for the SDK required: - type - session_id AdditionalInformation: type: object properties: account_information: type: object description: Information about the account provided by the merchant. properties: authentication: type: object properties: timestamp: type: string format: date-time description: The date and time the consumer logged in auth_method: type: string enum: - guest - merchant_credentials - sso - issuer_credentials - third_party - fido reference: type: string change_date: type: string description: The date the account was last changed format: date-time creation_date: type: string description: The date the account was opened by the consumer format: date-time number_of_purchases: type: integer description: Number of purchases in the last 6 months password_change_date: type: string description: > The date the consumer's password on the merchant's side was last changed format: date-time payments: type: object properties: day_count: type: integer description: > Number of payments in the last 24 hours (including abandoned transactions) year_count: type: integer description: > Number of payments in the previous year (including abandoned transactions) suspicious_activity: type: boolean description: > Indication that the merchant has expirienced suspicious activity on the customer account card_information: type: object properties: registration_date: type: string description: The date when the card was enrolled with the merchant format: date-time provision_attempts_last_twenty_four_hours: description: The number of the attempts to enroll a card in the last 24 hours type: integer cardholder_information: $ref: '#/components/schemas/CardholderInformation' purchase_information: type: object properties: delivery: type: object properties: e_mail: type: string timeframe: type: string enum: - electronic - sameday - nextday - standard gift_card: type: object properties: amount: type: number description: Total purchase price of prepaid card or gift card count: type: integer description: Total number of prepaid or gift cards purchased currency: type: string description: The ISO-4217 currency code pre_order: type: object properties: pre_order_date: type: string description: Expected product release date format: date-time reorder: type: boolean delivery_method: type: string enum: - billing_address - confirmed_address - other_address - store_or_pickup - digital - none - other AuthenticationPreference: type: string description: > The preference for the authentication method to be used for the payment. | Preference | Description | | ---------- | ---------------------------------------------------------------------------------------------------------------- | | NO_3RI | Don't perform 3RI authentication for this payment (Default). | | TRY_3RI | Try to perform 3RI authentication for this payment. If it fails the payment will still be sent for authorization. | | REQUIRE_3RI| Require 3RI authentication for this payment. If it fails the payment will not be sent for authorization. | default: NO_3RI enum: - NO_3RI - TRY_3RI - REQUIRE_3RI AuthenticationResult: type: object description: > The final result of the authentication. It holds in the cardholder authentication data (CAVV) and if there is a network token present, the token authentication data (TAVV). properties: cardholder_data: type: object description: The CAVV from the 3-D Secure authentication. properties: authentication_value: type: string ds_transaction_id: type: string eci: type: string acs_transaction_id: type: string challenge_cancel_reason: type: string status: type: string status_reason_code: type: string version: type: string required: - authentication_value - ds_transaction_id - eci encrypted_token_data: $ref: '#/components/schemas/EncryptedAuthenticationData' Amount: type: integer minimum: 0 description: > The amount given in minor units (e.g. use 700 for 7€). Some currencies do not support minor units (e.g. Japanese Yen). In this case send in the full value, .i.e. 100 for 100 JPY. CurrencyCode: type: string description: | The three letter currency code. See: [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) PaymentReference: type: string maxLength: 80 description: A description of the payment for later reference PaymentSource: description: |- The source that was used for the payment. | Type | Description | |------------|----------------------------------------------| | `card` | The payment method `card` was used as source | discriminator: propertyName: type mapping: card: $ref: '#/components/schemas/PaymentSourceCard' oneOf: - $ref: '#/components/schemas/PaymentSourceCard' PaymentSplitsResponse: description: > An array of split instructions. Data in this array is only processed on a Commerce account in the platform operating model. If you are in doubt, please reach out to your account representative. | Type | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | seller | Sending the given amount to the seller referenced by the `merchant_id` in the payload. The seller needs to be onboarded to the account and linked to the processor in order to receive funds from a payment split. | | commission | An already existing Commerce token can be used as source for the payment. | type: array minItems: 1 items: type: object discriminator: propertyName: type mapping: seller: $ref: '#/components/schemas/PaymentSplitSeller' commission: $ref: '#/components/schemas/PaymentSplitCommission' oneOf: - $ref: '#/components/schemas/PaymentSplitSeller' - $ref: '#/components/schemas/PaymentSplitCommission' PaymentStatus: type: string enum: - open - processing - failed - authorized - capturing - captured - settling - settled - voiding - voided UseCase: type: string description: Definition of the payment use-case for processing enum: - ONE_OFF - UNSCHEDULED - SUBSEQUENT_UNSCHEDULED - RECURRING - SUBSEQUENT_RECURRING Metadata: type: object description: > Metadata consisting of entries, each of which each includes a key and an associated value: * Maximum 20 key-value pairs. * Maximum 20 characters per key. * Maximum 80 characters per value. example: my_key_one: my_value_one my_key_two: my_value_two ErrorStatusCode: type: integer description: The corresponding HTTP status code for the error ErrorClassifier: type: string description: Technical code that helps to identify the error ErrorMessage: type: string description: Human readable representation of the error CardholderInformation: type: object properties: separate_shipping_address: type: boolean description: | If true the request also accepts the `shipping_address` object. If false it'll use the `billing_address` as `shipping_address`. billing_address: $ref: '#/components/schemas/EMVCoAddressRecord' email: type: string minLength: 1 maxLength: 254 home_phone: $ref: '#/components/schemas/PhoneRecord' mobile_phone: $ref: '#/components/schemas/PhoneRecord' shipping_address: $ref: '#/components/schemas/EMVCoAddressRecord' work_phone: $ref: '#/components/schemas/PhoneRecord' EncryptedAuthenticationData: type: string description: > JWE encrypted JSON string containing authentication data. Encrypted in a symmetric way with the shared encryption key using "alg"=A256GCMKW and "enc"="A256GCM". For decryption make sure the shared secret is hashed with a sha256 digest. The decrypted JSON has the following format: ```json { network_token: { token: "token_value", expiry_year: 2023, expiry_month: 12 }, cryptogram: "cryptogram_value", eci: "eci_value" } ``` - The field `network_token` contains the value of the token, the year of expiry and the month of expiry of the token and is always included. - The field `cryptogram` contains the value of the cryptogram and is always included. - The field `eci` can instead have a value if there was an Electronic Commerce Indicator assigned, or it can be `null` if no information was provided. PaymentSourceCard: type: object properties: type: type: string description: The type of payment-method that was used as source cardholder_name: type: string expiry_month: type: integer description: The number of month in a year (e.g. April is 4) expiry_year: type: integer description: The year given as four digit number (e.g. 2023) issuer: type: object properties: account: type: object properties: funding: type: string enum: - credit - debit - prepaid - charge - deferred debit country_code: $ref: '#/components/schemas/CountryCode_3166_2' currency: $ref: '#/components/schemas/CurrencyCode' identification_number: type: string description: The issuer idenfication number (IIN) - also know as BIN name: type: string description: The name of the bank scheme: type: string description: The scheme in which the card was issued segment: type: string enum: - consumer - business - commercial - other masked_account_number: type: string description: > The full lenght of the card number, but masked to conform to PCI DSS requirments pan_type: type: string description: > The type of primary account number (PAN) which used for this the payment. `DPAN` indicates a network token was used and `FPAN` indicates the full card was used. enum: - FPAN - DPAN required: - type - cardholder_name - expiry_month - expiry_year - masked_account_number - pan_type PaymentSplitSeller: type: object properties: type: type: string merchant_id: type: string format: uuid amount: type: integer description: | The amount to be sent to the respective merchant account. It considers the payment's currency selection. reference: type: string description: A reference for the seller split. required: - type - merchant_id - amount - reference PaymentSplitCommission: type: object properties: type: type: string amount: type: integer description: > The amount to be sent to the platform account in terms of a commission. It considers the payment's currency selection. reference: type: string description: A reference for the commission split. required: - type - amount - reference EMVCoAddressRecord: type: object description: An EMVCo compatible address record properties: city: type: string minLength: 1 maxLength: 50 country: $ref: '#/components/schemas/ISO3166-3-CountryCode' line_1: type: string minLength: 1 maxLength: 50 line_2: type: string minLength: 1 maxLength: 50 line_3: type: string minLength: 1 maxLength: 50 postal_code: type: string minLength: 1 maxLength: 16 state: type: string minLength: 1 maxLength: 3 PhoneRecord: type: object properties: country_code: type: string minLength: 1 maxLength: 3 number: type: string minLength: 1 maxLength: 15 CountryCode_3166_2: type: string description: The ISO 3166 two letter country code ISO3166-3-CountryCode: type: string description: | A three letter country code. [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) responses: 401_UnauthorizedError: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 401 message: No valid means of authentication was provided classifier: UNAUTHORIZED 403_ForbiddenError: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 403 message: Not allowed to access this resource or feature classifier: FORBIDDEN 422_ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorValidation' example: code: 422 classifier: VALIDATION_ERROR message: Validation error validation_errors: - path: json-path message: human readable error message securitySchemes: APIKeyAuth: type: apiKey name: X-API-Key in: header ````