> ## 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. # Create batch transaction refund > Create a refund for all instruments on a transaction. This endpoint requires the `transactions.write` scope. ## OpenAPI ````yaml /openapi.speakeasy.json POST /transactions/{transaction_id}/refunds/all 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 - 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: /transactions/{transaction_id}/refunds/all: post: tags: - Refunds summary: Create batch transaction refund description: Create a refund for all instruments on a transaction. operationId: create_full_transaction_refund parameters: - name: transaction_id in: path required: true schema: type: string format: uuid description: The ID of the transaction examples: - 7099948d-7286-47e4-aad8-b68f7eb44591 title: Transaction Id description: The ID of the transaction - name: x-gr4vy-merchant-account-id in: header required: false schema: anyOf: - type: string - type: 'null' description: The ID of the merchant account to use for this request. examples: - default title: X-Gr4Vy-Merchant-Account-Id description: The ID of the merchant account to use for this request. x-speakeasy-name-override: merchantAccountId - name: idempotency-key in: header required: false schema: anyOf: - type: string - type: 'null' description: >- A unique key that identifies this request. Providing this header will make this an idempotent request. We recommend using V4 UUIDs, or another random string with enough entropy to avoid collisions. examples: - request-12345 title: Idempotency-Key description: >- A unique key that identifies this request. Providing this header will make this an idempotent request. We recommend using V4 UUIDs, or another random string with enough entropy to avoid collisions. requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/TransactionRefundAllCreate' - type: 'null' title: Body responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Refunds' '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: 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.transactions.refunds.all.create("7099948d-7286-47e4-aad8-b68f7eb44591"); console.log(result); } 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()) ) as g_client: res = g_client.transactions.refunds.all.create(transaction_id="7099948d-7286-47e4-aad8-b68f7eb44591", reason="Refund due to user request.", external_identifier="refund-12345") # Handle response print(res) - lang: go label: Go source: "package main\n\nimport(\n\t\"context\"\n\t\"os\"\n\tgr4vygo \"github.com/gr4vy/gr4vy-go\"\n\t\"github.com/gr4vy/gr4vy-go/models/components\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := gr4vygo.New(\n gr4vygo.WithMerchantAccountID(\"default\"),\n gr4vygo.WithSecurity(os.Getenv(\"GR4VY_BEARER_AUTH\")),\n )\n\n res, err := s.Transactions.Refunds.All.Create(ctx, \"7099948d-7286-47e4-aad8-b68f7eb44591\", nil, &components.TransactionRefundAllCreate{\n Reason: gr4vygo.Pointer(\"Refund due to user request.\"),\n ExternalIdentifier: gr4vygo.Pointer(\"refund-12345\"),\n })\n if err != nil {\n log.Fatal(err)\n }\n if res != nil {\n // handle response\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(); $transactionRefundAllCreate = new Gr4vy\TransactionRefundAllCreate( reason: 'Refund due to user request.', externalIdentifier: 'refund-12345', ); $response = $sdk->transactions->refunds->all->create( transactionId: '7099948d-7286-47e4-aad8-b68f7eb44591', transactionRefundAllCreate: $transactionRefundAllCreate ); if ($response->refunds !== null) { // handle response } - lang: java label: Java source: >- package hello.world; import com.gr4vy.sdk.Gr4vy; import com.gr4vy.sdk.models.components.TransactionRefundAllCreate; import com.gr4vy.sdk.models.errors.*; import com.gr4vy.sdk.models.operations.CreateFullTransactionRefundResponse; import java.lang.Exception; public class Application { public static void main(String[] args) throws Exception { Gr4vy sdk = Gr4vy.builder() .merchantAccountId("default") .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", "")) .build(); CreateFullTransactionRefundResponse res = sdk.transactions().refunds().all().create() .transactionId("7099948d-7286-47e4-aad8-b68f7eb44591") .transactionRefundAllCreate(TransactionRefundAllCreate.builder() .reason("Refund due to user request.") .externalIdentifier("refund-12345") .build()) .call(); if (res.refunds().isPresent()) { System.out.println(res.refunds().get()); } } } - lang: csharp label: C# source: |- using Gr4vy; using Gr4vy.Models.Components; var sdk = new Gr4vySDK( id: "example", server: SDKConfig.Server.Sandbox, bearerAuthSource: Auth.WithToken(privateKey), merchantAccountId: "default" ); var res = await sdk.Transactions.Refunds.All.CreateAsync( transactionId: "7099948d-7286-47e4-aad8-b68f7eb44591", transactionRefundAllCreate: new TransactionRefundAllCreate() { Reason = "Refund due to user request.", ExternalIdentifier = "refund-12345", } ); // handle response components: schemas: TransactionRefundAllCreate: properties: reason: anyOf: - type: string maxLength: 100 - type: 'null' title: Reason description: An optional reason to attach extra context to the refund requests. examples: - Refund due to user request. external_identifier: anyOf: - type: string maxLength: 300 minLength: 1 - type: 'null' title: External Identifier description: >- An external identifier that can be used to match the refunds against your own records. examples: - refund-12345 additionalProperties: false type: object title: TransactionRefundAllCreate Refunds: properties: items: items: $ref: '#/components/schemas/Refund' 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: Refunds 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 Refund: properties: type: type: string const: refund title: Type description: Always `refund`. default: refund examples: - refund id: type: string format: uuid title: Id description: The unique identifier for the refund. examples: - 6a1d4e46-14ed-4fe1-a45f-eff4e025d211 transaction_id: type: string format: uuid title: Transaction Id description: The ID of the transaction associated with this refund. examples: - 7099948d-7286-47e4-aad8-b68f7eb44591 payment_service_refund_id: anyOf: - type: string maxLength: 300 minLength: 1 - type: 'null' title: Payment Service Refund Id description: The payment service's unique ID for the refund. examples: - refund_xYqd43gySMtori status: description: The status of the refund. examples: - succeeded type: string enum: - processing - succeeded - failed - declined - voided title: RefundStatus x-speakeasy-unknown-values: allow overlay: 1.0.0 currency: type: string pattern: ^[A-Z]{3}$ title: Currency description: >- The ISO 4217 currency code for this refund. Will always match that of the associated transaction. examples: - EUR - GBP - USD amount: type: integer maximum: 99999999 minimum: 0 title: Amount description: >- The amount of this refund, in the smallest currency unit (for example, cents or pence). examples: - 1299 reason: anyOf: - type: string - type: 'null' title: Reason description: The reason for this refund. Could be a multiline string. examples: - Refund due to user request. target_type: description: The type of the instrument that was refunded. examples: - payment-method type: string enum: - payment-method - gift-card-redemption title: RefundTargetType x-speakeasy-unknown-values: allow overlay: 1.0.0 target_id: anyOf: - type: string format: uuid - type: 'null' title: Target Id description: >- The optional ID of the instrument that was refunded. This may be `null` if the instrument was not stored. examples: - 07e70d14-a0c0-4ff5-bd4a-509959af0e4d reconciliation_id: type: string title: Reconciliation Id description: >- The base62 encoded refund ID. This represents a shorter version of this refund's `id` which is sent to payment services, anti-fraud services, and other connectors. You can use this ID to reconcile a payment service's refund against our system. examples: - 7jZXl4gBUNl0CnaLEnfXbt external_identifier: anyOf: - type: string - type: 'null' title: External Identifier description: >- An external identifier that can be used to match the refund against your own records. examples: - refund-12345 transaction_reconciliation_id: type: string title: Transaction Reconciliation Id description: >- The base62 encoded transaction ID. This represents a shorter version of the related transaction's `id` which is sent to payment services, anti-fraud services, and other connectors. You can use this ID to reconcile a payment service's transaction against our system. examples: - aLEnfXbt7jZXl4gBUNl0Cn transaction_external_identifier: anyOf: - type: string - type: 'null' title: Transaction External Identifier description: >- An external identifier that can be used to match the transaction against your own records. examples: - transaction-12345 created_at: type: string format: date-time title: Created At description: The date this refund was created at. examples: - '2013-07-16T19:23:00.000+00:00' updated_at: type: string format: date-time title: Updated At description: The date this refund was last updated at. examples: - '2013-07-16T19:23:00.000+00:00' creator: anyOf: - $ref: '#/components/schemas/Creator' - type: 'null' description: The user that created this resource examples: - email_address: jhon.doe@gr4vy.com id: 07e70d14-a0c0-4ff5-bd4a-509959af0e4d name: Jhon Doe error_code: anyOf: - type: string - type: 'null' title: Error Code description: The standardized error code set by Gr4vy. examples: - service_error raw_response_code: anyOf: - type: string - type: 'null' title: Raw Response Code description: >- This is the response code received from the payment service. This can be set to any value and is not standardized across different payment services. examples: - E104 raw_response_description: anyOf: - type: string - type: 'null' title: Raw Response Description description: ' This is the response description received from the payment service. This can be set to any value and is not standardized across different payment services.' examples: - Missing redirect URL additionalProperties: false type: object required: - id - transaction_id - status - currency - amount - target_type - reconciliation_id - transaction_reconciliation_id - created_at - updated_at title: Refund ErrorDetail: properties: location: description: >- The part of the request where the property can be found that caused the error. examples: - body type: string enum: - query - body - path - header - unknown title: ErrorLocation x-speakeasy-unknown-values: allow overlay: 1.0.0 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 Creator: properties: id: type: string format: uuid title: Id name: type: string title: Name email_address: type: string title: Email Address additionalProperties: false type: object required: - id - name - email_address title: Creator securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````