openapi: 3.2.0 info: title: Gr4vy Metrics Explorer API version: 1.1.0-beta contact: name: Gr4vy Support email: code@gr4vy.com url: https://gr4vy.com termsOfService: https://gr4vy.com license: name: MIT url: https://raw.githubusercontent.com/gr4vy/gr4vy-openapi/main/LICENSE description: 'Welcome to the Gr4vy API reference documentation. Our API is still very much a work in product and subject to change.' servers: - url: https://api.sandbox.{id}.gr4vy.app x-speakeasy-server-id: sandbox variables: id: default: example description: The subdomain for your Gr4vy instance. - url: https://api.{id}.gr4vy.app x-speakeasy-server-id: production variables: id: default: example description: The subdomain for your Gr4vy instance. security: - bearerAuth: [] tags: - name: Metrics Explorer description: Endpoints to retrieve the data used for the Metrics Explorer. x-internal: true paths: /metrics-explorer/{source}/metrics/{metric}/modules/{module}: parameters: - schema: type: string enum: - authentication - authorization example: authorization in: path name: source description: 'The set of transactions used as a source to calculate metrics. The source names are related to the Insights tab in the dashboard.' required: true - schema: type: string enum: - auth_rate - transactions - volume example: transactions in: path name: metric description: The metric to be calculated. required: true - schema: type: string enum: - authentication_outcome - authorized - country - currency - error_code - instrument_type - is_subsequent_payment - liability_shifted - merchant_initiated - metadata - method - payment_method_bin - payment_method_card_issuer_name - payment_method_card_type - payment_method_country - payment_method_scheme - payment_service - payment_source - raw_response_code - rule_route_transaction - rule_skip_3ds - three_d_secure_auth_resp - three_d_secure_eci - three_d_secure_method example: payment_service in: path name: module description: The module to be calculated. required: true get: operationId: get-metrics-explorer-module summary: Get Metrics Explorer module data description: 'Retrieves the data for a module in the Metrics Explorer. **Important:** The currency filter query parameter is **required** when the `metric` is set to `volume`.' tags: - Metrics Explorer x-internal: true parameters: - schema: type: string enum: - 1-day - 7-days - 30-days example: 7-days in: query name: period description: 'Filters the results to the set of data aggregated over the duration of the specified period.' required: true - schema: type: string enum: - succeeded - failed - abandoned example: abandoned in: query name: authentication_outcome description: 'Filters the results to only include transactions whose authentication process ended with the specified outcome. This parameter also accepts the null character `\0` to include transactions that didn''t undergo an authentication process.' required: false - schema: type: string enum: - '0' - '1' example: '1' in: query name: authorized description: Filters the results to only include transactions that were authorized (1) or declined (0). required: false - schema: type: string example: GB in: query name: country description: 'Filters the results to only include transactions that were processed in the specified country. The country code should be in the ISO 3166-1 two letter format. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: GBP in: query name: currency description: Filters the results to only include transactions that were processed in the specified currency. The currency code should be in the ISO 4217 format.
**Important:** This query parameter is **required** when the `metric` is set to `volume`. required: false - schema: type: string example: invalid_credentials in: query name: error_code description: 'Filters the results to only include transactions that failed with the specified error code. The error code is a string that describes the reason for the failure. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string description: 'The name of the instrument used to process the transaction. ' enum: - applepay - card_token - googlepay - network_token - pan - redirect - redirect_token example: network_token in: query name: instrument_type description: 'Filters the results to only include transactions that used the specified instrument type. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string enum: - '0' - '1' example: '1' in: query name: is_subsequent_payment description: 'Filters the results to only include transactions that are subsequent payments. A subsequent payment is a payment that is made after an initial payment, typically in a subscription or recurring payment scenario. The value should be either "0" (false) or "1" (true).' required: false - schema: type: string enum: - '0' - '1' example: '1' in: query name: liability_shifted description: Filters the results to only include transactions where liability was shifted (1) or was not shifted (0). required: false - schema: type: string enum: - '0' - '1' example: '1' in: query name: merchant_initiated description: 'Filters the results to only include transactions that were initiated by the merchant. The value should be either "0" (false) or "1" (true).' required: false - schema: type: string example: '{"key": "value"}' in: query name: metadata description: Filters the results to only include transactions that have the specified metadata. The metadata should be in JSON format and contain a single key-value pair. required: false - schema: type: string example: card enum: - affirm - afterpay - alipay - alipayhk - applepay - bacs - bancontact - banked - becs - bitpay - boleto - boost - card - cashapp - chaseorbital - checkout-session - clearpay - click-to-pay - dana - dcb - dlocal - ebanx - efecty - eps - everydaypay - gcash - gem - gemds - gift-card - giropay - givingblock - gocardless - googlepay - googlepay_pan_only - gopay - grabpay - id - ideal - kakaopay - kcp - klarna - latitude - latitudeds - laybuy - linepay - linkaja - maybankqrpay - mercadopago - multibanco - multipago - netbanking - network-token - oney_3x - oney_4x - oney_6x - oney_10x - oney_12x - ovo - oxxo - payid - paymaya - paypal - paypalpaylater - payto - venmo - pix - pse - rabbitlinepay - razorpay - scalapay - sepa - shopeepay - singteldash - smartpay - sofort - spei - stripedd - thaiqr - touchngo - truemoney - trustly - trustlyeurope - upi - vipps - waave - webpay - wechat - zippay in: query name: method description: 'Filters the results to only include transactions that were processed using the specified payment method. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: '123456' in: query name: payment_method_bin description: 'Filters the results to only include transactions that used the specified payment method bin. The payment method bin is the first 6 digits of the card number. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: Barclays in: query name: payment_method_card_issuer_name description: 'Filters the results to only include transactions that were processed with the specified card issuer name. The card issuer name is the name of the bank or financial institution that issued the card used for the transaction. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: credit enum: - credit - debit - prepaid in: query name: payment_method_card_type description: 'Filters the results to only include transactions that used the specified card type. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: GB in: query name: payment_method_country description: 'Filters the results to only include transactions that were processed with a card issued in the specified country. The country code should be in the ISO 3166-1 two letter format. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: visa enum: - accel - amex - bancontact - carte-bancaire - cirrus - culiance - dankort - diners-club - discover - eftpos-australia - elo - hipercard - jcb - maestro - mastercard - mir - nyce - other - pulse - rupay - star - uatp - unionpay - visa - null in: query name: payment_method_scheme description: 'Filters the results to only include transactions that were processed with the specified payment method scheme. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: 06319aec-2c0f-4c7b-8af1-047ca037fc021 in: query name: payment_service_id description: 'Filters the results to only include transactions that were processed with the specified payment service ID. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: recurring enum: - ecommerce - moto - recurring - installment - card_on_file in: query name: payment_source description: Filters the results to only include transactions that were processed with the specified payment source. required: false - schema: type: string example: COMPLETED in: query name: raw_response_code description: 'Filters the results to only include transactions that received the specified raw response code from the payment service. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: c2fefd1b-6ed0-4038-bbc8-48ea2fb7e9f7 in: query name: rule_id_route_transaction description: 'Filters the results to only include transactions that were processed with the specified routing rule. The rule ID should be in UUID format. This parameter also accepts the null character `\0` to include transactions that were not processed by any routing rule.' required: false - schema: type: string example: c2fefd1b-6ed0-4038-bbc8-48ea2fb7e9f7 in: query name: rule_id_skip_3ds description: 'Filters the results to only include transactions that were processed with the specified 3DS rule. The rule ID should be in UUID format. This parameter also accepts the null character `\0` to include transactions that were not processed by any 3DS rule.' required: false - schema: type: string example: Y in: query name: three_d_secure_auth_resp description: 'Filters the results to only include transactions that received the specified response during 3DS authentication. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: '05' in: query name: three_d_secure_eci description: 'Filters the results to only include transactions that received the specified ECI during 3DS authentication. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string enum: - challenge - frictionless example: frictionless in: query name: three_d_secure_method description: 'Filters the results to only include transactions that underwent 3DS authentication with the specified method. This parameter also accepts the null character `\0` to include transactions that didn''t undergo 3DS authentication.' required: false responses: '200': description: Returns the module's data. content: application/json: schema: type: array items: $ref: '#/components/schemas/MetricsExplorerModule' '400': description: Returns an error if the request was badly formatted or missing required fields. content: application/json: schema: $ref: '#/components/schemas/Error400BadRequest' '401': description: Returns an error if no valid authentication was provided. content: application/json: schema: $ref: '#/components/schemas/Error401Unauthorized' /metrics-explorer/{source}/metrics/{metric}/totals: parameters: - schema: type: string enum: - authentication - authorization example: authorization in: path name: source description: 'The set of transactions used as a source to calculate metrics. The source names are related to the Insights tab in the dashboard.' required: true - schema: type: string enum: - auth_rate - transactions - volume example: transactions in: path name: metric description: The metric to be calculated. required: true get: operationId: get-metrics-explorer-totals summary: Get Metrics Explorer line chart and summary data description: 'Retrieves the data for the line chart and summary in the Metrics Explorer. **Important:** The currency filter query parameter is **required** when the `metric` is set to `volume`.' tags: - Metrics Explorer x-internal: true parameters: - schema: type: string enum: - 1-day - 7-days - 30-days example: 7-days in: query name: period description: 'Filters the results to the set of data aggregated over the duration of the specified period.' required: true - schema: type: boolean default: false example: false in: query name: exclude_previous description: 'If set to `true`, aggregations and data from the previous period will not be calculated nor returned.' - schema: type: string enum: - succeeded - failed - abandoned example: abandoned in: query name: authentication_outcome description: 'Filters the results to only include transactions whose authentication process ended with the specified outcome. This parameter also accepts the null character `\0` to include transactions that didn''t undergo an authentication process.' required: false - schema: type: string enum: - '0' - '1' example: '1' in: query name: authorized description: Filters the results to only include transactions that were authorized (1) or declined (0). required: false - schema: type: string example: GB in: query name: country description: 'Filters the results to only include transactions that were processed in the specified country. The country code should be in the ISO 3166-1 two letter format. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: GBP in: query name: currency description: Filters the results to only include transactions that were processed in the specified currency. The currency code should be in the ISO 4217 format.
**Important:** This query parameter is **required** when the `metric` is set to `volume`. required: false - schema: type: string example: invalid_credentials in: query name: error_code description: 'Filters the results to only include transactions that failed with the specified error code. The error code is a string that describes the reason for the failure. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string description: 'The name of the instrument used to process the transaction. ' enum: - applepay - card_token - googlepay - network_token - pan - redirect - redirect_token example: network_token in: query name: instrument_type description: 'Filters the results to only include transactions that used the specified instrument type. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string enum: - '0' - '1' example: '1' in: query name: is_subsequent_payment description: 'Filters the results to only include transactions that are subsequent payments. A subsequent payment is a payment that is made after an initial payment, typically in a subscription or recurring payment scenario. The value should be either "0" (false) or "1" (true).' required: false - schema: type: string enum: - '0' - '1' example: '1' in: query name: liability_shifted description: Filters the results to only include transactions where liability was shifted (1) or was not shifted (0). required: false - schema: type: string enum: - '0' - '1' example: '1' in: query name: merchant_initiated description: 'Filters the results to only include transactions that were initiated by the merchant. The value should be either "0" (false) or "1" (true).' required: false - schema: type: string example: '{"key": "value"}' in: query name: metadata description: Filters the results to only include transactions that have the specified metadata. The metadata should be in JSON format and contain a single key-value pair. required: false - schema: type: string example: card enum: - affirm - afterpay - alipay - alipayhk - applepay - bacs - bancontact - banked - becs - bitpay - boleto - boost - card - cashapp - chaseorbital - checkout-session - clearpay - click-to-pay - dana - dcb - dlocal - ebanx - efecty - eps - everydaypay - gcash - gem - gemds - gift-card - giropay - givingblock - gocardless - googlepay - googlepay_pan_only - gopay - grabpay - id - ideal - kakaopay - kcp - klarna - latitude - latitudeds - laybuy - linepay - linkaja - maybankqrpay - mercadopago - multibanco - multipago - netbanking - network-token - oney_3x - oney_4x - oney_6x - oney_10x - oney_12x - ovo - oxxo - payid - paymaya - paypal - paypalpaylater - payto - venmo - pix - pse - rabbitlinepay - razorpay - scalapay - sepa - shopeepay - singteldash - smartpay - sofort - spei - stripedd - thaiqr - touchngo - truemoney - trustly - trustlyeurope - upi - vipps - waave - webpay - wechat - zippay in: query name: method description: 'Filters the results to only include transactions that were processed using the specified payment method. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: '123456' in: query name: payment_method_bin description: 'Filters the results to only include transactions that used the specified payment method bin. The payment method bin is the first 6 digits of the card number. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: Barclays in: query name: payment_method_card_issuer_name description: 'Filters the results to only include transactions that were processed with the specified card issuer name. The card issuer name is the name of the bank or financial institution that issued the card used for the transaction. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: credit enum: - credit - debit - prepaid in: query name: payment_method_card_type description: 'Filters the results to only include transactions that used the specified card type. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: GB in: query name: payment_method_country description: 'Filters the results to only include transactions that were processed with a card issued in the specified country. The country code should be in the ISO 3166-1 two letter format. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: visa enum: - accel - amex - bancontact - carte-bancaire - cirrus - culiance - dankort - diners-club - discover - eftpos-australia - elo - hipercard - jcb - maestro - mastercard - mir - nyce - other - pulse - rupay - star - uatp - unionpay - visa - null in: query name: payment_method_scheme description: 'Filters the results to only include transactions that were processed with the specified payment method scheme. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: 06319aec-2c0f-4c7b-8af1-047ca037fc021 in: query name: payment_service_id description: 'Filters the results to only include transactions that were processed with the specified payment service ID. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: recurring enum: - ecommerce - moto - recurring - installment - card_on_file in: query name: payment_source description: Filters the results to only include transactions that were processed with the specified payment source. required: false - schema: type: string example: COMPLETED in: query name: raw_response_code description: 'Filters the results to only include transactions that received the specified raw response code from the payment service. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: c2fefd1b-6ed0-4038-bbc8-48ea2fb7e9f7 in: query name: rule_id_route_transaction description: 'Filters the results to only include transactions that were processed with the specified routing rule. The rule ID should be in UUID format. This parameter also accepts the null character `\0` to include transactions that were not processed by any routing rule.' required: false - schema: type: string example: c2fefd1b-6ed0-4038-bbc8-48ea2fb7e9f7 in: query name: rule_id_skip_3ds description: 'Filters the results to only include transactions that were processed with the specified 3DS rule. The rule ID should be in UUID format. This parameter also accepts the null character `\0` to include transactions that were not processed by any 3DS rule.' required: false - schema: type: string example: Y in: query name: three_d_secure_auth_resp description: 'Filters the results to only include transactions that received the specified response during 3DS authentication. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string example: '05' in: query name: three_d_secure_eci description: 'Filters the results to only include transactions that received the specified ECI during 3DS authentication. This parameter also accepts the null character `\0` to include transactions that have a null for this field.' required: false - schema: type: string enum: - challenge - frictionless example: frictionless in: query name: three_d_secure_method description: 'Filters the results to only include transactions that underwent 3DS authentication with the specified method. This parameter also accepts the null character `\0` to include transactions that didn''t undergo 3DS authentication.' required: false responses: '200': description: Returns the totals data. content: application/json: schema: $ref: '#/components/schemas/MetricsExplorerTotals' '400': description: Returns an error if the request was badly formatted or missing required fields. content: application/json: schema: $ref: '#/components/schemas/Error400BadRequest' '401': description: Returns an error if no valid authentication was provided. content: application/json: schema: $ref: '#/components/schemas/Error401Unauthorized' components: schemas: ErrorDetail: title: Error details description: Additional detail about the part of a request body that caused an issue. type: object x-tags: - Errors properties: location: type: string example: body description: The location where the error caused an issue. enum: - query - body - path - header type: type: string example: value_error.missing description: A unique identifier for the type of error that occurred. pointer: type: string example: /payment_method/number description: 'The exact item for which the validation did not succeed. This is a JSON pointer for request bodies, while for query, path, and header parameters it is the name of the parameter.' message: type: string example: field required description: A human readable message for this error detail. MetricsExplorerModule: title: Metrics Explorer Module type: object description: Data for a module in the Metrics Explorer. x-tags: - Metrics Explorer x-internal: true properties: type: type: string description: The type of this resource. enum: - metrics-explorer.module example: metrics-explorer.module key: type: string description: The key for the module data entry.
This key is the value that should be used as a filter when calling the endpoints. For example, for module `payment_service`, the key will be the id of the payment service (UUID), so it should be used to filter other modules using the `payment_service_id` filter. example: d8c3d939-d75d-4598-81c7-a13f8238e624 display_name: type: string description: The display name for the module data entry. example: Stripe (US) value: description: The value associated with the key. The type depends on the metric. oneOf: - type: integer description: This type is used for "volume" and "transactions" metrics. example: 100 - type: number description: This type is used for "authorization rate" metric. format: decimal example: 0.5 example: 100 metadata: type: - object - 'null' description: A dictionary containing metadata as key-value pairs. additionalProperties: type: string example: payment_service_definition_id: stripe-card Error401Unauthorized: title: Unauthorized Error type: object description: Unauthorized Error (HTTP 401). x-tags: - Errors properties: type: type: string description: '`error`.' enum: - error example: error code: type: string description: '`unauthorized`.' example: unauthorized enum: - unauthorized status: type: integer description: '`401`.' example: 401 enum: - 401 message: type: string description: No valid API authentication found. example: No valid API authentication found enum: - No valid API authentication found details: type: array description: 'A list of detail objects that further clarify the reason for the error. Not every error supports more detail.' example: [] items: $ref: '#/components/schemas/ErrorDetail' MetricsExplorerTotals: title: Metrics Explorer Totals type: object description: Data for totals in the Metrics Explorer. x-tags: - Metrics Explorer x-internal: true properties: type: type: string description: The type of this resource. example: metrics-explorer.totals enum: - metrics-explorer.totals series: type: object description: Contains two series of data points used to build the line chart. Each series contains aggregations of data created over the duration of the specified period (e.g. `7-days`). The `previous` series contains aggregations from the period immediately preceding the `current` series. properties: current: type: array description: Metrics for the transactions created during the current period aggregated by hour or day. The meaning of the values depends on the metric used to call the endpoint. "volume" and "transactions" metrics are represented as integers, while "authorization rate" metric is represented as decimal numbers. `null`s may be returned when there is no data for authorization rate to indicate that the metric is not applicable for the given time period. items: type: object properties: first_interval: type: string description: The date and time of the first data point, represented with an ISO 8601 interval value indicating whether it is aggregated by one hour (PT1H) or one day (P1D) periods. example: 2025-03-25T00:00:00Z/P1D values: type: array description: The values associated with the metric for the current period. "volume" and "transactions" metrics are represented as integers, while "authorization rate" metric is represented as decimal numbers. items: oneOf: - type: - integer - 'null' description: The values associated with the metric. This type is used for "volume" and "transactions" metrics. example: 10 - type: - number - 'null' format: decimal description: The value associated with the key. This type is used for "authorization rate" metric. example: 0.5 example: - 0.9 - 0.99 - 0.85 previous: type: - array - 'null' description: Metrics for the transactions created during the period immediately preceding the current period aggregated by hour or day. The meaning of the values depends on the metric used to call the endpoint. "volume" and "transactions" metrics are represented as integers, while "authorization rate" metric is represented as decimal numbers. `null`s may be returned when there is no data for authorization rate to indicate that the metric is not applicable for the given time period. items: type: object properties: first_interval: type: string description: The date and time of the first data point, represented with an ISO 8601 interval value indicating whether it is aggregated by one hour (PT1H) or one day (P1D) periods. example: 2025-03-25T00:00:00Z/P1D values: type: array description: The values associated with the metric for the previous period. "volume" and "transactions" metrics are represented as integers, while "authorization rate" metric is represented as decimal numbers. items: oneOf: - type: - integer - 'null' description: The value associated with the key. This type is used for "volume" and "transactions" metrics. example: 10 - type: - number - 'null' description: The value associated with the key. This type is used for "authorization rate" metric. format: decimal example: 0.5 example: - 0.9 - 0.99 - 0.85 example: current: - first_interval: 2025-03-25T00:00:00Z/PT1H values: - 0.9 - 0.99 - 0.85 previous: - first_interval: 2025-03-18T00:00:00Z/PT1H values: - 0.9 - 0.99 - 0.85 summary: type: object description: A summary of the totals data. properties: current: type: object description: The total value for the current period.
For `volume` and `transactions` metrics, the value is the sum of all values in the `current` series.
For `auth_rate` metric, the value is the count of authorized transactions over the count of processed transactions for the current period. properties: value: oneOf: - type: - integer - 'null' description: This type is used for "volume" and "transactions" metrics. - type: - number - 'null' description: This type is used for "authorization rate" metric. format: decimal previous: type: - object - 'null' description: The total value for the previous period.
For `volume` and `transactions` metrics, the value is the sum of all values in the `previous` series.
For `auth_rate` metric, the value is the count of authorized transactions over the count of processed transactions for the previous period. properties: value: oneOf: - type: - integer - 'null' description: This type is used for "volume" and "transactions" metrics. - type: - number - 'null' description: This type is used for "authorization rate" metric. format: decimal delta: type: - number - 'null' description: The difference between the current and previous values. Positive values indicate an increase, while negative values indicate a decrease.
For `volume` and `transactions` metrics, the value is the percentage change between the current and previous values, however, for `authorization rate` metric, the value is the absolute difference between the current and previous values. format: decimal example: 0.5 example: current: value: 90.5 previous: value: 80.5 delta: 10 Error400BadRequest: title: Bad Request type: object description: Bad Request (HTTP 400). x-tags: - Errors properties: type: type: string description: '`error`.' enum: - error example: error code: type: string description: A short code that describes the reason for the error. example: bad_request enum: - bad_request - incorrect_json - invalid_credentials status: type: integer description: '`400`.' example: 400 enum: - 400 message: type: string description: A human-readable reason for the error. example: Missing '****' field details: type: array description: A list of detail objects that further clarify the reason for the error. items: $ref: '#/components/schemas/ErrorDetail' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT