Giftcard API

Giftcards are claims on locked value, not free-form codes. Creation, purchase, redemption, and merchant redemption all depend on escrow-backed funds and fraud controls.

Merchant redemption

Use a server-side secret key with the giftcards:redeem scope. A public key cannot redeem value.
Redemptions are idempotent and support authorise, capture, void, refund, and reverse states. The GiftCard must be active and escrow-backed.
Fulfil only after verifying the API result or a signed webhook; never treat a browser redirect as proof of payment.

Endpoints

Endpoint	Method	Auth	Headers	Notes
List or create giftcards `/giftcards/api/giftcards/` Create a user or merchant giftcard and lock value in escrow.	POST	User JWT Authenticated caller	`Authorization: Bearer <user-jwt>` `Content-Type: application/json`	Status lifecycle: created, active, redeemed, expired, cancelled, refunded Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Giftcard status `/giftcards/api/giftcards/status/{code}/` Resolve a giftcard by code and return its masked state.	GET	User JWT Authenticated caller	`Authorization: Bearer <user-jwt>` `Content-Type: application/json`	Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Redeem giftcard `/giftcards/api/redeem-giftcard/` Redeem a giftcard into an EgaCard wallet.	POST	User JWT Authenticated caller	`Authorization: Bearer <user-jwt>` `Content-Type: application/json`	Webhooks: giftcard.redeemed, wallet.credited Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Redeem merchant giftcard `/business/api/v1/public/giftcards/redeem/` Authorise or immediately capture an escrow-backed GiftCard for an external platform.	POST	Merchant HMAC Authenticated caller	`X-EGACARD-API-KEY: <merchant-public-key>` `X-EGACARD-SIGNATURE: <hmac-signature>` `X-EGACARD-TIMESTAMP: <unix-timestamp>` `X-EGACARD-IDEMPOTENCY-KEY: <unique-request-key>`	Parameters: credential — GiftCard token or code (required) pin — required when the card is PIN protected merchant_reference — unique order reference amount and currency — optional partial redemption capture — true for immediate capture terminal_id, channel_id, external_user_id and metadata — optional reconciliation context Idempotency: Required Status lifecycle: authorised, captured, voided, refunded, reversed Webhooks: gift_card.redeemed, redemption.captured, redemption.refunded Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Request {'credential': 'gc_live_…', 'pin': '••••', 'merchant_reference': 'order_1042', 'amount': '125.00', 'currency': 'USD', 'capture': True} Response {'reference': 'EGC-GCR-…', 'status': 'captured', 'merchant_reference': 'order_1042', 'amount': '125.00', 'currency': 'USD'}
Capture GiftCard redemption `/business/api/v1/payments/redemptions/{reference}/capture` Capture a previously authorised redemption.	POST	Merchant HMAC Authenticated caller	`X-EGACARD-API-KEY: <merchant-public-key>` `X-EGACARD-SIGNATURE: <hmac-signature>` `X-EGACARD-TIMESTAMP: <unix-timestamp>` `X-EGACARD-IDEMPOTENCY-KEY: <unique-request-key>`	Idempotency: Required Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Void GiftCard redemption `/business/api/v1/payments/redemptions/{reference}/void` Release an uncaptured authorisation.	POST	Merchant HMAC Authenticated caller	`X-EGACARD-API-KEY: <merchant-public-key>` `X-EGACARD-SIGNATURE: <hmac-signature>` `X-EGACARD-TIMESTAMP: <unix-timestamp>` `X-EGACARD-IDEMPOTENCY-KEY: <unique-request-key>`	Idempotency: Required Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Refund GiftCard redemption `/business/api/v1/payments/redemptions/{reference}/refund` Refund all or part of a captured redemption.	POST	Merchant HMAC Authenticated caller	`X-EGACARD-API-KEY: <merchant-public-key>` `X-EGACARD-SIGNATURE: <hmac-signature>` `X-EGACARD-TIMESTAMP: <unix-timestamp>` `X-EGACARD-IDEMPOTENCY-KEY: <unique-request-key>`	Idempotency: Required Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits