Create refund for a payment

Docs/

API reference

Create refund for a payment

Request

Creates refund for a payment entity if the payment is in success state and no other refund exists.

Security

JWT

Bodyapplication/jsonrequired

reasonstringrequired

The reason for the refund. Send one of the listed values exactly as written: the match is case-sensitive and includes the spaces, so Requested By Customer is accepted and requested_by_customer or Requested by customer is rejected with a 400.

Enum:"Requested By Customer""Duplicate""Fraudulent""Others"

payment_idstringrequired

The unique identifier of payment linked to refund.

Example:"payt_E602dMzgjpDC"

document_idstring

The id of document that is uploaded for refund.

Example:"doc_E602dMd2adDC"

document_urlstring

The url of document that is uploaded for refund.

Example:"https://www.example.com/documents/invoice.pdf"

file_namestring

The name of document that is uploaded for refund.

Example:"invoice"

amountinteger

The amount to refund, in the smallest unit of the payment's converted_currency, the merchant-side currency (cents for USD), or the currency received for a bank transfer not yet matched to a payin. 1000 is $10.00 when that currency is USD. Required for partial refunds. If not provided, the full payment amount will be refunded. If partial refunds are not enabled on your account, an amount below the payment's converted_amount is rejected with 400 and the message Partial refunds are not enabled for this business, and an amount equal to or greater than it refunds the full payment. The refund returns its own amount in the refund's currency, which can differ from this one.

Example:1000

request_idstring

Your unique identifier for this refund, used to reject duplicates. If a refund with the same request_id already exists on your account, the request is rejected with 400 and the message Refund already exists for this request_id, unless the payment first fails another refund check (for example, it's already fully refunded). The existing refund is not returned. Look it up with GET /v1/refunds?request_id=<your_request_id>.

Example:"unique_refund_request_id_123"

curl -i -X POST \
  https://api.glomopay.com/api/v1/refunds \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "Requested By Customer",
    "payment_id": "payt_E602dMzgjpDC",
    "document_id": "doc_E602dMd2adDC",
    "document_url": "https://www.example.com/documents/invoice.pdf",
    "file_name": "invoice",
    "amount": 1000,
    "request_id": "unique_refund_request_id_123"
  }'

Responses

Refund created successfully

Bodyapplication/json

idstringread-only

The unique identifier for the refund.

Example:"refund_6776d57dnbTWj"

customer_idstring

The unique identifier of customer linked to refund.

Example:"cust_E602dMzgjpDC"

payment_idstring

The unique identifier of payment linked to refund.

Example:"payt_E602dMzgjpDC"

reasonstring

The reason for the refund. For a refund you created, this is the reason you sent.

Glomo also refunds some payments itself, and those refunds appear in your refund list with one of two further reasons that you cannot send:

Refunded For Subscription Verification — the refund of a small charge used to verify the card when a subscription was set up.
Refunded For Subscription Card Update — the refund of a small charge used to verify a new card when the card on a subscription was replaced.

Enum:"Requested By Customer""Fraudulent""Duplicate""Others""Refunded For Subscription Verification""Refunded For Subscription Card Update"

Example:"Requested By Customer"

feesobject

The fees charged for the refund.

balance_usedobject

The balance deducted to process the refund, with amount in the smallest unit of currency.

documentsArray of any

statusstringread-only

The status of the refund.

in_progress — the refund has been accepted and is being sent back to the customer.
under_review — the refund is being reviewed by Glomo before it is processed.
action_required — Glomo needs more information before the refund can proceed. Respond to the open RFI to continue.
success — the refund has been paid out. Terminal.
failed — the refund could not be completed. Terminal.
cancelled — the refund was stopped before it was paid out. Terminal.

Enum:"in_progress""under_review""action_required""success""failed""cancelled"

Example:"success"

currencystring, (iso-4217)

The currency code in ISO 4217 format. For example, USD.

Example:"USD"

amountnumber, >= 1

The refund amount, in the smallest unit of currency (cents for USD). 1000 is $10.00 when currency is USD. currency is the payment's payment_currency (the currency the customer paid in), or its converted_currency when the payment has no payment_currency, so it can differ from the currency of the amount you send when creating the refund.

Example:1000

utrstringread-only

The Unique Transaction Reference (UTR) number associated with the refund.

Example:"UTR123456789"

partial_refundbooleanread-only

Indicates whether the refund is a partial refund.

Example:false

request_idstring or nullread-only

The request_id you sent when creating this refund; null if you sent none. Look the refund up with GET /v1/refunds?request_id=<your_request_id>.

Example:"your-internal-id"

created_atstring, (date-time)read-only

When the refund was created, as an ISO 8601 date-time in UTC.

Example:"2021-06-01T12:00:00Z"

updated_atstring, (date-time)read-only

When the refund was last updated, as an ISO 8601 date-time in UTC.

Example:"2021-06-01T12:00:00Z"

Response

{
  "id": "refund_6776d57dnbTWj",
  "customer_id": "cust_E602dMzgjpDC",
  "payment_id": "payt_E602dMzgjpDC",
  "reason": "Requested By Customer",
  "fees": {
    "fx_fees": { … },
    "txn_fees": { … }
  },
  "balance_used": {
    "currency": "USD",
    "amount": 1000
  },
  "documents": [
    { … }
  ],
  "status": "success",
  "currency": "USD",
  "amount": 1000,
  "utr": "UTR123456789",
  "partial_refund": false,
  "request_id": "your-internal-id",
  "created_at": "2021-06-01T12:00:00Z",
  "updated_at": "2021-06-01T12:00:00Z"
}