BYbyaccrue
Payments

Refund Payment

The refund endpoint can be called on a Payment that is in the Processing or Sent status and has at least one successful capture.

It supports partial refunds — the refund amount cannot exceed the captured amount, and the sum of all non-failed refunds cannot exceed the captured amount.

Calling the refund endpoint will never change the status of the payment so the status of the payment cannot be used to determine if it has been refunded.

When a Payment is refunded, an associated Refund object is created. The Refund object has an independent status representing the refund. The refund endpoint returns the Refund object created and can be included in the get payment endpoint.

Idempotency: The idempotencyKey field is required to prevent duplicate refund operations. If a refund with the same key already exists, the existing refund will be returned.

Disbursements: For pay-by-wallet refunds, you can optionally specify disbursement to indicate which counterparties to debit and for how much. The sum of disbursement amounts must equal the refund amount.

If disbursement is omitted, the system automatically derives proportional disbursements from the original payment's disbursement breakdown. The refund amount is distributed across the same counterparties using their original ratios. For full refunds the derived amounts match the original proportions exactly.

post/api/v1/payments/{paymentId}/refund

Request

Path parameters

paymentIdstring uuid required

Payment ID

Example:123e4567-e89b-12d3-a456-426614174000

Headers

Client-IDstring uuid required

The unique identifier of the client making the request. This header is required to retrieve the client-specific configuration and ensure that the response is tailored to the client's settings and permissions.

Example:123e4567-e89b-12d3-a456-426614174000
Authorizationstring uuid required

Secure secret to access privileged endpoints.

Example:Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef

Request body

Example request

{
  "data": {
    "attributes": {
      "idempotencyKey": "refund-order-12345",
      "disbursement": [
        {
          "counterpartyId": "9f755746-13cb-4d0b-81f2-3b4f1b44f6d8",
          "amount": 500
        },
        {
          "counterpartyId": "4cf95060-dd01-42ac-9020-8ca42004920d",
          "amount": 500
        }
      ]
    }
  }
}

Response

OK

Example response

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "relationships": {
      "paymentIntent": {
        "links": {
          "self": "/api/v1/payment-intents/497f6eca-6276-4993-bfeb-53cbbbba6f08"
        }
      },
      "refunds": {
        "data": [
          {
            "id": "9f755746-13cb-4d0b-81f2-3b4f1b44f6d8",
            "type": "Refund"
          }
        ]
      },
      "captures": {
        "data": [
          {
            "id": "4cf95060-dd01-42ac-9020-8ca42004920d",
            "type": "Capture"
          }
        ]
      }
    },
    "links": {
      "virtualDebitCard": "https://secure-api.accruesavings.com/api/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/card"
    },
    "attributes": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "Sent",
      "amount": 9999,
      "channel": "ORG-1",
      "reference": "MERCHANT-GENERATED-TOKEN",
      "disbursement": [
        {
          "counterpartyId": "9f755746-13cb-4d0b-81f2-3b4f1b44f6d8",
          "amount": 800,
          "fee": 10,
          "remit": true
        },
        {
          "counterpartyId": "4cf95060-dd01-42ac-9020-8ca42004920d",
          "amount": 200,
          "fee": 5,
          "remit": true
        }
      ],
      "charges": {
        "fee": {
          "amount": 150,
          "type": "pay_by_wallet"
        },
        "rewards": 1000
      },
      "deductions": {
        "rewards": 1000,
        "fees": 150
      }
    }
  },
  "links": {
    "self": "/api/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/refund"
  },
  "included": [
    {
      "id": "9f755746-13cb-4d0b-81f2-3b4f1b44f6d8",
      "type": "Refund",
      "attributes": {
        "status": "Sent",
        "amount": 1000,
        "message": "Refund processed. Fee: 59 cents",
        "reference": "MERCHANT-GENERATED-TOKEN",
        "charges": {
          "fee": {
            "amount": 59,
            "type": "pay_by_wallet_refund"
          },
          "rewards": 0
        },
        "deductions": {
          "rewards": 0,
          "fees": 59
        },
        "id": "9f755746-13cb-4d0b-81f2-3b4f1b44f6d8",
        "createdAt": "2024-06-19T12:19:17.031Z",
        "updatedAt": "2024-06-19T12:19:17.064Z"
      }
    },
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "type": "PaymentIntent",
      "attributes": {
        "status": "PromotedToPayment",
        "amount": 9999,
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "expiresAt": "2024-12-19T10:39:59.447Z",
        "createdAt": "2024-06-19T10:39:59.452Z",
        "updatedAt": "2024-06-19T10:43:59.337Z"
      },
      "relationships": {
        "client": {
          "data": {
            "id": "b5f8c9d2-1a3e-4f5b-8c7d-9e0f1a2b3c4d",
            "type": "Client"
          }
        }
      }
    },
    {
      "id": "4cf95060-dd01-42ac-9020-8ca42004920d",
      "type": "Capture",
      "attributes": {
        "id": "4cf95060-dd01-42ac-9020-8ca42004920d",
        "createdAt": "2024-06-19T12:00:00.000Z",
        "updatedAt": "2024-06-19T12:00:00.000Z",
        "method": "Direct",
        "amount": 9999
      }
    },
    {
      "id": "b5f8c9d2-1a3e-4f5b-8c7d-9e0f1a2b3c4d",
      "type": "Client",
      "attributes": {
        "id": "b5f8c9d2-1a3e-4f5b-8c7d-9e0f1a2b3c4d",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-06-19T10:00:00.000Z",
        "allowedOrigins": [
          "https://example.com"
        ],
        "preferredStorage": {
          "Web": "localStorage"
        },
        "merchantId": "123e4567-e89b-12d3-a456-426614174000",
        "merchantName": "Example Merchant",
        "containerPlacements": {},
        "containerDisplayRules": {},
        "containerIntegrityEffects": {},
        "copyAdjustments": {},
        "rewardsFlowType": "Instant",
        "rewardsRateType": "Purchase",
        "widgetCustomizations": {}
      }
    }
  ],
  "meta": {
    "message": "Full refund will be initiated after the original payment is successfully received."
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.