> ## Documentation Index > Fetch the complete documentation index at: https://docs.bnplx.io/llms.txt > Use this file to discover all available pages before exploring further. # Refunds - Create > Creates a refund against an already processed payment. In case of some processors, you can even opt to refund only a partial amount multiple times until the original charge amount has been refunded ## OpenAPI ````yaml openapi_spec post /refunds openapi: 3.0.3 info: title: GreenBanana - API Documentation description: > ## Get started GreenBanana provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library. We have a testing environment referred to "sandbox", which you can setup to test API calls without affecting production data. Currently, our sandbox environment is live while our production environment is under development and will be available soon. You can sign up on our Dashboard to get API keys to access GreenBanana API. ### Environment Use the following base URLs when making requests to the APIs: | Environment | Base URL | |---------------|------------------------------------| | Sandbox | | | Production | | ## Authentication When you sign up on our [dashboard](https://app.bnplx.io) and create a merchant account, you are given a secret key (also referred as api-key) and a publishable key. You may authenticate all API requests with GreenBanana server by providing the appropriate key in the request Authorization header. | Key | Description | |-----------------|-----------------------------------------------------------------------------------------------| | api-key | Private key. Used to authenticate all API requests from your merchant server | | publishable key | Unique identifier for your account. Used to authenticate API requests from your app's client | Never share your secret api keys. Keep them guarded and secure. contact: name: GreenBanana Support url: https://api.staging.bnplx.io email: support@greenbanana.group license: name: Apache-2.0 version: 0.1.0 servers: - url: https://api.staging.bnplx.io description: Sandbox Environment security: [] tags: - name: Guide description: Follow this guide to do your first BNPL payment with GreenBanana - name: Merchant Account description: Create and manage merchant accounts - name: Profile description: Create and manage profiles - name: Merchant Connector Account description: Create and manage merchant connector accounts - name: Payments description: Create and manage one-time payments, recurring payments and mandates - name: Refunds description: Create and manage refunds for successful payments - name: Mandates description: Manage mandates - name: Customers description: Create and manage customers - name: Payment Methods description: Create and manage payment methods of customers - name: Products description: Create and manage products in the merchant catalog - name: Disputes description: Manage disputes - name: API Key description: Create and manage API Keys - name: payment link description: Create payment link - name: Routing description: Create and manage routing configurations - name: Event description: Manage events paths: /refunds: post: tags: - Refunds summary: Refunds - Create description: >- Creates a refund against an already processed payment. In case of some processors, you can even opt to refund only a partial amount multiple times until the original charge amount has been refunded operationId: Create a Refund requestBody: content: application/json: schema: $ref: '#/components/schemas/RefundRequest' examples: Create an instant refund to refund partial amount: value: amount: 5125 capture_id: '{{payment_id}}_1_1' metadata: birth_date: '2001-10-19' buyer_type: private_person customer_locale: en-US device_token: abcddef gender: M order_dttm: '2028-10-01 10:10:10.222' partner_shop_id: INTEGRATION_TE_DACH settlement: settlement1234 user_language_code: 208 order_details: - amount: 5000 product_id: i124 product_name: Apple airpods quantity: 1 tax_amount: 125 tax_percentage: 10 reason: Customer returned product Create an instant refund to refund the whole amount: value: amount: 10250 capture_id: '{{payment_id}}_1_1' metadata: birth_date: '2001-10-19' buyer_type: private_person customer_locale: en-US device_token: abcddef gender: M order_dttm: '2028-10-01 10:10:10.222' partner_shop_id: INTEGRATION_TE_DACH settlement: settlement1234 user_language_code: 208 order_details: - amount: 5000 product_id: i124 product_name: Apple iphone 14 quantity: 1 tax_amount: 125 tax_percentage: 10 - amount: 5000 product_id: i124 product_name: Apple airpods quantity: 1 tax_amount: 125 tax_percentage: 10 payment_id: '{{payment_id}}' reason: Customer returned product refund_type: instant Create an instant refund with reason: value: amount: 5125 capture_id: '{{payment_id}}_1_1' payment_id: '{{payment_id}}' reason: Customer returned product refund_type: instant required: true responses: '200': description: Refund created content: application/json: schema: $ref: '#/components/schemas/RefundResponse' '400': description: Missing Mandatory fields security: - api_key: [] components: schemas: RefundRequest: type: object required: - payment_id properties: payment_id: type: string description: The payment id against which refund is to be initiated example: pay_mbabizu24mvu3mela5njyhpit4 maxLength: 30 minLength: 30 refund_id: type: string description: >- Unique Identifier for the Refund. This is to ensure idempotency for multiple partial refunds initiated against the same payment. If this is not passed by the merchant, this field shall be auto generated and provided in the API response. It is recommended to generate uuid(v4) as the refund_id. example: ref_mbabizu24mvu3mela5njyhpit4 nullable: true maxLength: 30 minLength: 30 capture_id: type: string description: >- The identifier for the payment invoice to be refunded in case the connector supports this feature nullable: true merchant_id: type: string description: The identifier for the Merchant Account example: y3oqhf46pyzuxjbcn2giaqnb44 nullable: true maxLength: 255 amount: type: integer format: int64 description: >- Total amount for which the refund is to be initiated. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., If not provided, this will default to the full payment amount example: 6540 nullable: true minimum: 100 reason: type: string description: >- Reason for the refund. Often useful for displaying to users and your customer support executive. In case the payment went through Stripe, this field needs to be passed with one of these enums: `duplicate`, `fraudulent`, or `requested_by_customer` example: Customer returned the product nullable: true maxLength: 255 refund_type: allOf: - $ref: '#/components/schemas/RefundType' default: Instant nullable: true metadata: type: object description: >- You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. nullable: true merchant_connector_details: allOf: - $ref: '#/components/schemas/MerchantConnectorDetailsWrap' nullable: true split_refunds: allOf: - $ref: '#/components/schemas/SplitRefund' nullable: true order_details: type: array items: $ref: '#/components/schemas/OrderDetailsWithAmount' description: Order details for the refund example: |- [{ "product_name": "Apple iPhone 16", "quantity": 1, "amount" : 69000 "product_img_link" : "https://dummy-img-link.com" }] nullable: true additionalProperties: false RefundResponse: type: object required: - refund_id - payment_id - amount - currency - status - connector properties: refund_id: type: string description: Unique Identifier for the refund payment_id: type: string description: The payment id against which refund is initiated amount: type: integer format: int64 description: >- The refund amount, which should be less than or equal to the total payment amount. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc example: 6540 minimum: 100 currency: type: string description: The three-letter ISO currency code status: $ref: '#/components/schemas/RefundStatus' reason: type: string description: >- An arbitrary string attached to the object. Often useful for displaying to users and your customer support executive nullable: true metadata: type: object description: >- You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object nullable: true error_message: type: string description: The error message nullable: true error_code: type: string description: The code for the error nullable: true unified_code: type: string description: >- Error code unified across the connectors is received here if there was an error while calling connector nullable: true unified_message: type: string description: >- Error message unified across the connectors is received here if there was an error while calling connector nullable: true created_at: type: string format: date-time description: The timestamp at which refund is created nullable: true updated_at: type: string format: date-time description: The timestamp at which refund is updated nullable: true connector: type: string description: The connector used for the refund and the corresponding payment example: stripe profile_id: type: string description: The id of business profile for this refund nullable: true merchant_connector_id: type: string description: >- The merchant_connector_id of the processor through which this payment went through nullable: true split_refunds: allOf: - $ref: '#/components/schemas/SplitRefund' nullable: true order_details: type: array items: $ref: '#/components/schemas/OrderDetailsWithAmount' description: The order details for the refund nullable: true capture_id: type: string description: The identifier for the payment capture to be refunded nullable: true RefundType: type: string description: To indicate whether to refund needs to be instant or scheduled enum: - scheduled - instant MerchantConnectorDetailsWrap: type: object description: Merchant connector details used to make payments. required: - creds_identifier properties: creds_identifier: type: string description: >- Creds Identifier is to uniquely identify the credentials. Do not send any sensitive info, like encoded_data in this field. And do not send the string "null". encoded_data: allOf: - $ref: '#/components/schemas/MerchantConnectorDetails' nullable: true SplitRefund: oneOf: - type: object required: - stripe_split_refund properties: stripe_split_refund: $ref: '#/components/schemas/StripeSplitRefundRequest' description: >- Charge specific fields for controlling the revert of funds from either platform or connected account. Check sub-fields for more details. OrderDetailsWithAmount: type: object required: - product_name - quantity - amount properties: product_name: type: string description: Name of the product that is being purchased example: shirt maxLength: 255 quantity: type: integer format: int32 description: The quantity of the product to be purchased example: 1 minimum: 0 amount: type: integer format: int64 description: >- the amount per quantity of product, this is the amount before tax is added to it requires_shipping: type: boolean nullable: true product_img_link: type: string description: The image URL of the product nullable: true product_link: type: string description: The URL of the product nullable: true product_id: type: string description: ID of the product that is being purchased nullable: true category: allOf: - $ref: '#/components/schemas/ProductCategory' nullable: true sub_category: type: string description: Sub category of the product that is being purchased nullable: true brand: type: string description: Brand of the product that is being purchased nullable: true product_type: allOf: - $ref: '#/components/schemas/ProductType' nullable: true tax_percentage: type: integer format: int32 description: Tax of the product in percentage nullable: true product_tax_code: type: string description: The tax code for the product nullable: true tax_amount: allOf: - $ref: '#/components/schemas/MinorUnit' nullable: true RefundStatus: type: string description: The status for refunds enum: - succeeded - failed - pending - review MerchantConnectorDetails: type: object properties: connector_account_details: type: object description: >- Account details of the Connector. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Useful for storing additional, structured information on an object. nullable: true metadata: type: object description: >- Metadata is useful for storing additional, unstructured information on an object. nullable: true StripeSplitRefundRequest: type: object description: >- Charge specific fields for controlling the revert of funds from either platform or connected account for Stripe. Check sub-fields for more details. properties: revert_platform_fee: type: boolean description: >- Toggle for reverting the application fee that was collected for the payment. If set to false, the funds are pulled from the destination account. nullable: true revert_transfer: type: boolean description: >- Toggle for reverting the transfer that was made during the charge. If set to false, the funds are pulled from the main platform's account. nullable: true additionalProperties: false ProductCategory: type: string enum: - regular - shipping_costs - gift_card - discount - voucher - return_costs ProductType: type: string enum: - physical - digital - travel - ride - event - accommodation - variable MinorUnit: type: integer format: int64 description: This Unit struct represents MinorUnit in which core amount works securitySchemes: api_key: type: apiKey in: header name: api-key description: >- Use the API key created under your merchant account from the GreenBanana dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application. ````