> ## Documentation Index > Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt > Use this file to discover all available pages before exploring further. # List payment service definitions > List the definitions of each payment service that can be configured. This API is different from the [list connection definitions](../connections/list-connection-definitions) because it only returns definitions for payment services and not anti-fraud and gift card services. This endpoint requires the `payment-service-definitions.read` scope. ## OpenAPI ````yaml openapi.speakeasy.json GET /payment-service-definitions openapi: 3.1.0 info: title: Gr4vy description: The Gr4vy API. version: 1.0.0 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: 3DS scenarios description: Manage and create 3DS scenarios in sandbox. - name: Account updater description: Schedule stored cards for an account update. - name: Audit logs description: Query user activity. - name: Buyers description: Manage buyers. - name: Buyers - Gift cards description: Query gift cards for buyers. - name: Buyers - Payment methods description: Query payment methods for buyers. - name: Buyers - Shipping details description: Manage shipping details for buyers. - name: Card details description: Returns information about a card. - name: Card scheme definitions description: List definitions for card schemes. - name: Checkout sessions description: Manage checkout sessions. - name: Digital wallets - Sessions description: Create sessions for digital wallets like Apple Pay and Google Pay. - name: Digital wallets - Setup description: Manage digital wallets like Apple Pay and Google Pay. - name: Gift cards description: Manage stored gift cards. - name: Insights description: Retrieve Insights data. - name: Insights - Presets description: Manage presets for Insights. - name: Merchant accounts description: Manage merchant accounts in an instance. - name: Merchant accounts - 3DS configuration description: Manage 3DS profiles for merchant accounts. - name: Monitoring description: Manage monitoring and alerting. - name: Payment links description: Manage payment links. - name: Payment methods description: Manage stored payment methods. - name: Payment methods - Definitions description: Manage payment method definitions. - name: Payment methods - Network tokens description: Manage network tokens for stored payment methods. - name: Payment methods - Payment service tokens description: Manage payment service tokens for stored payment methods. - name: Payment options description: Fetch a list of payment options to display at checkout. - name: Payment service definitions description: Fetch info about the definition of each payment service. - name: Payment services description: Manage configured payment services. - name: Payouts description: Payout API. - name: Refunds description: Manage transaction refunds. - name: Reports description: Manage one-off and scheduled reports. - name: Reports - Executions description: Manage executions of reports. - name: Transactions description: Manage transaction. - name: Transactions - Actions description: Read Flow actions triggered for a transaction. - name: Transactions - Captures description: Read transaction capture data. - name: Transactions - Chargebacks description: Read transaction chargeback data. - name: Transactions - Chargeback reversals description: Read transaction chargeback reversal data. - name: Transactions - Settlements description: Read transaction settlement data. - name: Transactions - Sessions description: Manage transaction session data. - name: Webhook subscriptions description: Manage webhook subscriptions. paths: /payment-service-definitions: get: tags: - Payment service definitions summary: List payment service definitions description: List the definitions of each payment service that can be configured. operationId: list_payment_service_definitions parameters: - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: A pointer to the page of results to return. examples: - ZXhhbXBsZTE title: Cursor description: A pointer to the page of results to return. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: The maximum number of items that are at returned. examples: - 20 default: 20 title: Limit description: The maximum number of items that are at returned. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PaymentServiceDefinitions' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: The request was unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: >- The credentials were invalid or the caller did not have permission to act on the resource. content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: The resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error404' '405': description: The request method was not allowed. content: application/json: schema: $ref: '#/components/schemas/Error405' '409': description: A duplicate record was found. content: application/json: schema: $ref: '#/components/schemas/Error409' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '425': description: The request was too early. content: application/json: schema: $ref: '#/components/schemas/Error425' '429': description: Too many requests were made. content: application/json: schema: $ref: '#/components/schemas/Error429' '500': description: The server encountered an error. content: application/json: schema: $ref: '#/components/schemas/Error500' '502': description: The server encountered an error. content: application/json: schema: $ref: '#/components/schemas/Error502' '504': description: The server encountered an error. content: application/json: schema: $ref: '#/components/schemas/Error504' x-codeSamples: - lang: csharp label: C# source: >- using Gr4vy; using Gr4vy.Models.Components; using Gr4vy.Models.Requests; var sdk = new Gr4vySDK( id: "example", server: SDKConfig.Server.Sandbox, bearerAuthSource: Auth.WithToken(privateKey), merchantAccountId: "default" ); ListPaymentServiceDefinitionsResponse? res = await sdk.PaymentServiceDefinitions.ListAsync( cursor: "ZXhhbXBsZTE", limit: 20 ); while(res != null) { // handle items res = await res.Next!(); } - lang: javascript label: TypeScript source: |- import { Gr4vy, withToken } from "@gr4vy/sdk"; import fs from "fs"; const gr4vy = new Gr4vy({ id: "example", server: "sandbox", merchantAccountId: "default", bearerAuth: withToken({ privateKey: fs.readFileSync("private_key.pem", "utf8"), }), }); async function run() { const result = await gr4vy.paymentServiceDefinitions.list(); for await (const page of result) { console.log(page); } } run(); - lang: python label: Python source: |- from gr4vy import Gr4vy import os with Gr4vy( id="example", server="sandbox", merchant_account_id="default", bearer_auth=auth.with_token(open("./private_key.pem").read()) ): res = g_client.payment_service_definitions.list(cursor="ZXhhbXBsZTE", limit=20) while res is not None: # Handle items res = res.next() - lang: go label: Go source: "package main\n\nimport(\n\t\"context\"\n\t\"os\"\n\tgr4vygo \"github.com/gr4vy/gr4vy-go\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := gr4vy.New(\n\t\tgr4vy.WithID(\"example\"),\n\t\tgr4vy.WithServer(gr4vy.ServerSandbox),\n\t\tgr4vy.WithSecuritySource(withToken),\n\t\tgr4vy.WithMerchantAccountID(\"default\"),\n\t)\n\n res, err := s.PaymentServiceDefinitions.List(ctx, gr4vygo.Pointer(\"ZXhhbXBsZTE\"), gr4vygo.Pointer[int64](20))\n if err != nil {\n log.Fatal(err)\n }\n if res != nil {\n for {\n // handle items\n\n res, err = res.Next()\n\n if err != nil {\n // handle error\n }\n\n if res == nil {\n break\n }\n }\n }\n}" - lang: php label: PHP source: |- declare(strict_types=1); require 'vendor/autoload.php'; use Gr4vy; $sdk = Gr4vy\SDK::builder() ->setId('example') ->setServer('sandbox') ->setSecuritySource(Auth::withToken($privateKey)) ->setMerchantAccountId('default') ->build(); $responses = $sdk->paymentServiceDefinitions->list( cursor: 'ZXhhbXBsZTE', limit: 20 ); foreach ($responses as $response) { if ($response->statusCode === 200) { // handle response } } - lang: java label: Java source: >- package hello.world; import com.gr4vy.sdk.Gr4vy; import com.gr4vy.sdk.models.errors.*; import com.gr4vy.sdk.models.operations.ListPaymentServiceDefinitionsResponse; import java.lang.Exception; public class Application { public static void main(String[] args) throws Exception { Gr4vy sdk = Gr4vy.builder() .id("example") .server(AvailableServers.SANDBOX) .merchantAccountId("default") .securitySource(new BearerSecuritySource.Builder(privateKey).build()) .build(); sdk.paymentServiceDefinitions().list() .cursor("ZXhhbXBsZTE") .limit(20L) .callAsStream() .forEach((ListPaymentServiceDefinitionsResponse item) -> { // handle page }); } } components: schemas: PaymentServiceDefinitions: properties: items: items: $ref: '#/components/schemas/PaymentServiceDefinition' type: array title: Items description: A list of items returned for this request. limit: type: integer maximum: 100 minimum: 1 title: Limit description: The number of items for this page. default: 20 examples: - 20 next_cursor: anyOf: - type: string maxLength: 1000 minLength: 1 - type: 'null' title: Next Cursor description: The cursor pointing at the next page of items. examples: - ZXhhbXBsZTE previous_cursor: anyOf: - type: string maxLength: 1000 minLength: 1 - type: 'null' title: Previous Cursor description: The cursor pointing at the previous page of items. examples: - Xkjss7asS additionalProperties: false type: object required: - items title: PaymentServiceDefinitions Error400: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `bad_request` default: bad_request examples: - bad_request status: type: integer title: Status description: Always `400`. default: 400 examples: - 400 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error400 Error401: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `unauthorized` default: unauthorized examples: - unauthorized status: type: integer title: Status description: Always `401`. default: 401 examples: - 401 message: type: string title: Message description: A human readable message that provides more context to the error. default: No valid API authentication found examples: - No valid API authentication found details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error401 Error403: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `forbidden` default: forbidden examples: - forbidden status: type: integer title: Status description: Always `403`. default: 403 examples: - 403 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error403 Error404: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `not_found` default: not_found examples: - not_found status: type: integer title: Status description: Always `404`. default: 404 examples: - 404 message: type: string title: Message description: A human readable message that provides more context to the error. default: The resource could not be found examples: - The resource could not be found details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error404 Error405: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `method_not_allowed` default: method_not_allowed examples: - method_not_allowed status: type: integer title: Status description: Always `405`. default: 405 examples: - 405 message: type: string title: Message description: A human readable message that provides more context to the error. default: Method Not Allowed examples: - Method Not Allowed details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error405 Error409: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `duplicate_record` default: duplicate_record examples: - duplicate_record status: type: integer title: Status description: Always `409`. default: 409 examples: - 409 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] resource_id: anyOf: - type: string - type: 'null' title: Resource Id description: The ID of the conflicting resource. examples: - cdc70639-cb9c-4222-a73f-b8ce39f7821b additionalProperties: false type: object title: Error409 HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError Error425: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `too_early` default: too_early examples: - too_early status: type: integer title: Status description: Always `425`. default: 425 examples: - 425 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error425 Error429: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `too_many_requests` default: too_many_requests examples: - too_many_requests status: type: integer title: Status description: Always `429`. default: 429 examples: - 429 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error429 Error500: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `server_error` default: server_error examples: - server_error status: type: integer title: Status description: Always `500`. default: 500 examples: - 500 message: type: string title: Message description: A human readable message that provides more context to the error. default: Request could not be processed examples: - Request could not be processed details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error500 Error502: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `bad_gateway` default: bad_gateway examples: - bad_gateway status: type: integer title: Status description: Always `502`. default: 502 examples: - 502 message: type: string title: Message description: A human readable message that provides more context to the error. default: Request could not be processed examples: - Request could not be processed details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error502 Error504: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `gateway_timeout` default: gateway_timeout examples: - gateway_timeout status: type: integer title: Status default: 504 message: type: string title: Message description: A human readable message that provides more context to the error. default: Request could not be processed examples: - Request could not be processed details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error504 PaymentServiceDefinition: properties: id: type: string maxLength: 50 minLength: 1 title: Id description: >- The definition ID of the payment service that can be configured. This is the underlying provider followed by a dash followed by the method. examples: - adyen-ideal - stripe-card type: type: string const: payment-service-definition title: Type description: Always `payment-service-definition`. default: payment-service-definition examples: - payment-service-definition display_name: type: string maxLength: 200 minLength: 1 title: Display Name description: A human friendly name for this service. examples: - iDEAL - Stripe method: $ref: '#/components/schemas/Method' description: The method of the service examples: - ideal - card fields: items: $ref: '#/components/schemas/DefinitionField' type: array title: Fields description: >- A list of credentials and related fields which can be configured for this service. reporting_fields: items: $ref: '#/components/schemas/DefinitionField' type: array title: Reporting Fields description: A list of reporting fields which can be configured for this service. supported_currencies: items: type: string pattern: ^[A-Z]{3}$ examples: - EUR - GBP - USD type: array title: Supported Currencies description: >- A list of three-letter ISO currency codes that this service supports. examples: - - USD - GBP - EUR - AUD supported_countries: items: type: string pattern: ^[A-Z]{2}$ examples: - DE - GB - US type: array title: Supported Countries description: A list of two-letter ISO country codes that this service supports. examples: - US - GB - DE - AUD mode: $ref: '#/components/schemas/Mode' description: >- The mode that defines the flow this payment service uses to process a payment. examples: - card - redirect icon_url: anyOf: - type: string - type: 'null' title: Icon Url description: An icon to display for the payment service. examples: - https://example.com/icons/adyen-ideal.svg supported_features: additionalProperties: type: boolean type: object title: Supported Features description: Features supported by the payment service. required_checkout_fields: items: $ref: '#/components/schemas/RequiredCheckoutFields' type: array title: Required Checkout Fields description: >- A list of condition that define when some fields must be provided with a transaction request. configuration: $ref: '#/components/schemas/PaymentServiceConfiguration' description: Additional configuration on how to present the approval UI. supported_integration_clients: anyOf: - items: $ref: '#/components/schemas/IntegrationClient' type: array - type: 'null' title: Supported Integration Clients description: >- List of supported integration clients. Defaults to redirect for most redirect connectors. examples: - - redirect additionalProperties: false type: object required: - id - display_name - method - fields - reporting_fields - supported_currencies - supported_countries - mode - supported_features - required_checkout_fields - configuration - supported_integration_clients title: PaymentServiceDefinition ErrorDetail: properties: location: $ref: '#/components/schemas/ErrorLocation' description: >- The part of the request where the property can be found that caused the error. examples: - body pointer: anyOf: - type: string format: json-pointer - type: string title: Pointer description: A JSON pointer for the particular property that caused the error. examples: - /currency message: type: string title: Message description: A human-readdable explanation of the error. examples: - 'Unknown ISO 4217 currency code: USX' type: type: string title: Type description: The type of error that was raised for this property. examples: - value_error additionalProperties: false type: object required: - location - pointer - message - type title: ErrorDetail ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError Method: type: string title: Method DefinitionField: properties: key: type: string maxLength: 50 minLength: 1 title: Key description: The key of a field that can be submitted. examples: - private_api_key display_name: type: string maxLength: 200 minLength: 1 title: Display Name description: The human readable name for this field. examples: - Private API key required: type: boolean title: Required description: Defines if this field is required when the service is created. examples: - true format: $ref: '#/components/schemas/DefinitionFieldFormat' description: Defines the type of input that needs to be rendered for this field. examples: - text secret: type: boolean title: Secret description: >- Defines if this field is secret. When `true` the field's value is not returned when querying the payment service information. examples: - true verifiable: type: boolean title: Verifiable description: >- Defines if this field can be verified through the verify credentials button. examples: - true additionalProperties: false type: object required: - key - display_name - required - format - secret - verifiable title: DefinitionField description: >- A single field that needs to be submitted for a payment service when it is created. Mode: type: string title: Mode RequiredCheckoutFields: properties: required_fields: items: type: string type: array uniqueItems: true title: Required Fields description: >- A list of transaction fields that are required to process a payment for this service. examples: - - address.line1 - address.country - address.city - address.postal_code conditions: anyOf: - additionalProperties: true type: object - type: 'null' title: Conditions description: The conditions under which these fields are required examples: - country: - IN additionalProperties: false type: object required: - required_fields title: RequiredCheckoutFields description: >- A collection of checkout fields and the conditions under which they are required. PaymentServiceConfiguration: properties: approval_ui_target: $ref: '#/components/schemas/ApprovalTarget' description: >- The browser target that an approval URL must be opened in. If any or null, then there is no specific requirement. examples: - any approval_ui_height: type: string pattern: ^\d+(?:vh|px)$ title: Approval Ui Height description: >- Height of the approval interface in either pixels or view height (vh). examples: - 100px - 50vh approval_ui_width: type: string pattern: ^\d+(?:vw|px)$ title: Approval Ui Width description: Width of the approval interface in either pixels or view width (vw). examples: - 100px - 50vw cart_items_limit: type: integer title: Cart Items Limit description: >- The maximum number of cart items supported by this connector before we will truncate the list. examples: - 100 cart_items_required: type: boolean title: Cart Items Required description: Defines if cart items are required by this connector. examples: - true cart_items_should_match_amount: type: boolean title: Cart Items Should Match Amount description: >- Defines if the cart items sum value should match the transaction amount. examples: - true additionalProperties: false type: object required: - approval_ui_target - approval_ui_height - approval_ui_width - cart_items_limit - cart_items_required - cart_items_should_match_amount title: PaymentServiceConfiguration IntegrationClient: type: string title: IntegrationClient ErrorLocation: type: string title: ErrorLocation DefinitionFieldFormat: type: string title: DefinitionFieldFormat ApprovalTarget: type: string title: ApprovalTarget securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````