TagPayTagPay

API Reference

Refunds

A Refund returns funds to the customer who made an original charge. Refunds may be full or partial.

Create a refund

POST/v1/refunds

Refunds can only be issued for charges with status: success. Partial refunds reduce the remaining refundable balance.

Body parameters

charge_referencestringrequired

The reference of the original charge.

amountintegeroptional

Amount to refund in kobo. Defaults to the full remaining refundable amount.

reasonstringoptional

Free-text reason. Shown in dashboard.

metadataobjectoptional

Arbitrary key/value pairs for your own bookkeeping.

Response

200
idstring

TagPay-assigned refund ID.

charge_referencestring

Reference of the original charge.

amountinteger

Refunded amount in kobo.

statusenum<'pending' | 'success' | 'failed'>

Refund status.

created_atstring

ISO-8601 timestamp.

Errors

NOT_FOUND404No charge with that reference.
REFUND_EXCEEDS_BALANCE400Refund amount exceeds the remaining refundable balance.
CHARGE_NOT_REFUNDABLE400Charge has not succeeded yet, or is older than 90 days.

List refunds

GET/v1/refunds

Returns refunds in reverse-chronological order by default.

Query parameters

charge_referencestringoptional

Filter to refunds for a specific charge.

statusenum<'pending' | 'success' | 'failed'>optional

Filter by status.

fromstringoptional

ISO-8601 date — start of range.

tostringoptional

ISO-8601 date — end of range.

pageintegeroptional

Page number, 1-indexed.

per_pageintegeroptional

Results per page, max 100.

Response

200
dataarray<Refund>

Array of refund objects.

metaobject

Pagination metadata.

totalinteger

Total matching records.

pageinteger

Current page.

per_pageinteger

Per-page count.

Retrieve a refund

GET/v1/refunds/:id

Returns the full refund resource.

Path parameters

idstringrequired

Refund ID.

Response

200
idstring

TagPay-assigned refund ID.

charge_referencestring

Reference of original charge.

amountinteger

Amount in kobo.

statusstring

Status.