> ## Documentation Index
> Fetch the complete documentation index at: https://docs.momentco.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Redemption
> Creates a redemption. Final status depends on the selected provider's hold capability.
## OpenAPI
````yaml POST /collect/redemptions
openapi: 3.1.0
info:
version: 1.0.0
title: Redemptions API
description: Redemptions API
summary: Orchestrates redemption lifecycle against external providers.
contact:
name: Moment
url: https://momentco.net
email: support@momentco.net
license:
name: Proprietary
url: https://momentco.net/api-terms
servers:
- url: https://api.momentpay.net
security: []
tags:
- name: Redemptions
x-displayName: Redemptions
description: >-
A `Redemption` represents a stateful aggregate that clients drive from
`draft` through `reserved` to `confirmed`, with idempotent POST operations
against external voucher providers.
- name: Stored Value
x-displayName: Stored Value
description: >-
Stateless stored value queries against providers (balance lookup, voucher
metadata).
- name: Discovery
x-displayName: Discovery
description: >-
Static metadata describing the redemption types the API supports, their
capabilities, and the `source` attributes each requires. Lets headless
clients discover supported types dynamically.
- name: Events
x-displayName: Events
description: >
Outbound CloudEvents v1.0 envelopes emitted on every redemption state
transition. Delivered via change data capture from the `outbox_events`
collection to downstream consumers. Subscribers should be idempotent on
event `id` (at least once delivery).
- name: Redemption Model
x-displayName: Redemption Model
description: |
- name: Operation Model
x-displayName: Operation Model
description: |
- name: Change Voucher Model
x-displayName: Change Voucher Model
description: |
- name: CloudEvent Model
x-displayName: CloudEvent Envelope Model
description: |
CloudEvents v1.0 envelope used for all outbound redemption events.
- name: Problem Detail Model
x-displayName: Problem Detail Model
description: >
RFC 9457 problem details. Returned with `Content-Type:
application/problem+json` on every error response.
externalDocs:
description: Read the full API documentation
url: https://momentco.net/docs
paths:
/collect/redemptions:
post:
tags:
- Redemptions
summary: Create a redemption
description: >
Creates a redemption. Final status depends on the selected provider's
hold capability.
operationId: create_redemption
parameters:
- $ref: '#/components/parameters/idempotency_key'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_redemption_request'
examples:
Full value redeem (amount omitted):
$ref: '#/components/examples/full_value_redeem'
Confirmed full redeem:
$ref: '#/components/examples/confirmed_full_redeem'
Confirmed 1Voucher partial redeem:
$ref: '#/components/examples/confirmed_1voucher_partial_redeem'
Confirmed Blu partial redeem:
$ref: '#/components/examples/confirmed_blu_partial_redeem'
Failed voucher already used:
$ref: '#/components/examples/failed_voucher_already_used'
responses:
'201':
description: Redemption created. Status varies by provider capability.
content:
application/json:
schema:
$ref: '#/components/schemas/redemption'
examples:
Full value redeem (amount omitted):
$ref: '#/components/examples/full_value_redeem_response'
Confirmed full redeem:
$ref: '#/components/examples/confirmed_full_redeem_response'
Confirmed 1Voucher partial redeem:
$ref: >-
#/components/examples/confirmed_1voucher_partial_redeem_response
Confirmed Blu partial redeem:
$ref: '#/components/examples/confirmed_blu_partial_redeem_response'
Failed voucher already used:
$ref: '#/components/examples/failed_voucher_already_used_response'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'409':
$ref: '#/components/responses/idempotency_conflict'
'500':
$ref: '#/components/responses/internal_server_error'
security:
- bearer_auth: []
components:
parameters:
idempotency_key:
name: Idempotency-Key
in: header
required: false
description: >
Client supplied key. Replays return the original response within a 24
hour window. Replay with the same key but a different request body
returns `409 Conflict`.
schema:
type: string
minLength: 1
maxLength: 200
example: 9b8a3d2e-4f5b-4f5b-9b8a-3d2e4f5b4f5b
schemas:
create_redemption_request:
type: object
description: Request body for creating a new redemption.
required:
- type
- source
properties:
type:
$ref: '#/components/schemas/type'
source:
$ref: '#/components/schemas/source'
amount:
type: integer
minimum: 1
description: >
Amount in cents. Optional. When omitted, the voucher's full value is
redeemed. Provide `currency` whenever `amount` is supplied.
currency:
type: string
minLength: 3
maxLength: 3
example: ZAR
description: >
ISO 4217 currency code. Optional. When omitted, the voucher's full
value is redeemed in its native currency.
redemption_options:
type: object
additionalProperties: true
related_ids:
type: array
items:
type: string
metadata:
$ref: '#/components/schemas/metadata_fields'
external_reference:
type: string
redemption:
type: object
example:
id: rdm_6a0d5c7fe182228a6c64cb78
status: confirmed
version: 3
type: vouchers.one_voucher
provider_reference:
serial_number: '20260520082514335162'
amount: 6000
reserved_amount: 6000
redeemed_amount: 6000
reversed_amount: 0
currency: ZAR
source:
pin: '1115684091419838'
operations:
- id: mpd2156u_7cwvqp5m
type: reserve
status: succeeded
amount: 6000
provider_reference:
pin: '1115684091419838'
created_at: '2026-05-20T08:25:01.014Z'
- id: mpd2185c_vz0wyx10
type: confirm
status: succeeded
amount: 6000
provider_reference:
serial_number: '20260520082514335162'
created_at: '2026-05-20T08:25:14.248Z'
change_voucher:
pin: '2226897234561029'
serial_number: '20260520082514998877'
amount: 4000
expires_at: '2027-05-20T00:00:00Z'
status: issued
related_ids: []
metadata:
order_id: ord_789012
external_reference: order-2026-0001
created_at: '2026-05-20T08:24:56.501Z'
updated_at: '2026-05-20T08:25:14.249Z'
required:
- id
- status
- version
- amount
- reversed_amount
- currency
- operations
- related_ids
- created_at
- updated_at
properties:
id:
type: string
pattern: ^rdm_[a-f0-9]{24}$
example: rdm_663a1b9c8e4f2a0012abcd34
status:
$ref: '#/components/schemas/redemption_status'
version:
type: integer
minimum: 1
description: >-
Resource version for optimistic concurrency. Starts at 1 on creation
and increments on every state change. Use the latest value when
reconciling concurrent updates.
example: 3
type:
$ref: '#/components/schemas/type'
provider_reference:
type: object
additionalProperties: true
description: >-
Latest provider side reference bag. Shape depends on the most recent
operation.
amount:
type: integer
description: Requested amount in cents.
reserved_amount:
type: integer
description: Amount currently reserved against the provider in cents.
redeemed_amount:
type: integer
description: >-
Amount captured by the provider in cents. May differ from `amount`
on partial redeems.
reversed_amount:
type: integer
description: Amount reversed back to the provider in cents.
currency:
type: string
minLength: 3
maxLength: 3
example: ZAR
source:
$ref: '#/components/schemas/source'
redemption_options:
type: object
additionalProperties: true
description: Provider specific configuration bag forwarded on each operation.
operations:
type: array
items:
$ref: '#/components/schemas/operation'
change_voucher:
$ref: '#/components/schemas/change_voucher'
last_error:
$ref: '#/components/schemas/operation_error'
related_ids:
type: array
items:
type: string
metadata:
$ref: '#/components/schemas/metadata_fields'
external_reference:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
type:
title: Redemption Type
type: string
description: >
Namespaced redemption type in `category.type` form. The category selects
the value class and the suffix selects the specific provider that will
fulfil the redemption.
Only the `vouchers` category is available today. Loyalty point
categories (for example `loyalty_points.skywards`,
`loyalty_points.ebucks`) are planned.
enum:
- vouchers.one_voucher
- vouchers.ott
- vouchers.blu
source:
title: Source
description: >
Provider specific source credential object that identifies the voucher
being redeemed. The shape is owned by the adapter and selected by the
parent `type` field.
oneOf:
- title: 1Voucher
type: object
required:
- pin
properties:
pin:
type: string
description: 16 digit voucher PIN. Sensitive value. Masked in service logs.
additionalProperties: false
- title: OTT
type: object
required:
- pin
- phone_number
properties:
pin:
type: string
description: Voucher PIN or token. Sensitive value.
phone_number:
type: string
description: Subscriber phone number associated with the voucher.
additionalProperties: false
- title: Blu
type: object
required:
- token
properties:
token:
type: string
description: Blu voucher token or PIN. Sensitive value.
additionalProperties: false
metadata_fields:
type: object
description: >
Set of key-value pairs that you can attach to an object. This can be
useful
for storing additional information about the object in a structured
format.
NEW
**Limitations:**
- Maximum 20 keys
- Key names must be strings (max 40 characters)
- Values must be strings (max 500 characters)
additionalProperties:
type: string
example:
customer_id: cust_123456
order_id: ord_789012
redemption_status:
type: string
description: Lifecycle status of the redemption aggregate.
enum:
- draft
- reserved
- confirmed
- failed
operation:
type: object
description: >-
Individual operation recorded against a redemption (a reserve or a
confirm attempt).
required:
- id
- type
- status
- amount
- created_at
properties:
id:
type: string
description: Unique identifier for the operation.
example: mpd2156u_7cwvqp5m
type:
$ref: '#/components/schemas/operation_type'
status:
$ref: '#/components/schemas/operation_status'
amount:
type: integer
description: Operation amount in cents.
example: 1900
provider_reference:
type: object
additionalProperties: true
description: >-
Provider specific reference bag (for example `{ pin }` after
reserve, `{ serial_number }` after confirm).
error:
$ref: '#/components/schemas/operation_error'
created_at:
type: string
format: date-time
change_voucher:
title: Change Voucher
description: >
Replacement voucher issued by the provider when a partial redemption is
performed (redeemed amount less than the original voucher value).
Populated by 1Voucher and Blu today. The shape is selected by the
redemption `type`.
Customer must keep `pin` to spend the remainder. `amount`, when present,
is in cents. Blu does not return an amount for the replacement voucher,
so the field is omitted. Caller can issue a stored value lookup against
`pin` for the balance.
oneOf:
- title: 1Voucher
type: object
required:
- pin
- serial_number
- status
properties:
pin:
type: string
description: Voucher PIN or token. Sensitive value. Masked in service logs.
serial_number:
type: string
description: Voucher serial number.
amount:
type: integer
description: Change voucher value in cents.
expires_at:
type: string
description: Provider formatted expiry. Format depends on the provider.
status:
type: string
description: Provider reported voucher status (for example `issued`).
additionalProperties: false
- title: Blu
type: object
description: >-
Blu does not return an amount for the replacement voucher, so
`amount` is omitted.
required:
- pin
- serial_number
- reference
properties:
pin:
type: string
description: Voucher PIN or token. Sensitive value. Masked in service logs.
serial_number:
type: string
description: Voucher serial number.
expires_at:
type: string
description: Provider formatted expiry. Format depends on the provider.
reference:
type: string
description: New voucher reference.
barcode:
oneOf:
- type: integer
- type: string
description: Printable barcode for the customer.
product_name:
type: string
description: For example `Chat 4 Change Vodacom Voucher`.
product_instructions:
type: string
description: For example `TO RECHARGE DIAL:*130*TOKEN#`.
product_help:
type: string
description: 'For example `Customer Care: SMS ''help'' to 30505.`'
customer_message:
type: string
description: For example `No Refunds. Vouchers cannot be reprinted`.
additionalProperties: false
operation_error:
type: object
description: >-
Provider mapped error attached to a failed operation or to a failed
redemption aggregate.
required:
- error_code
- message
properties:
error_code:
type: string
description: >-
Provider namespaced error code (for example `1Voucher.2402`,
`1Voucher.transport_error`).
example: 1Voucher.2402
message:
type: string
description: Human readable explanation supplied by the provider.
example: The voucher you have entered could not be found
problem_detail:
type: object
description: >
RFC 9457 problem details. Returned with `Content-Type:
application/problem+json` on every error response.
required:
- type
- title
- status
- code
properties:
type:
type: string
format: uri
description: A URI reference identifying the problem type.
example: https://api.momentco.io/problems/resource_not_found
title:
type: string
description: A short, human readable summary of the problem type.
example: Resource Not Found
status:
type: integer
description: The HTTP status code applicable to this problem.
example: 404
detail:
type: string
description: A human readable explanation specific to this occurrence.
example: Redemption rdm_663a1b9c8e4f2a0012abcd34 not found
instance:
type: string
description: A URI reference identifying the specific occurrence (request path).
example: /collect/redemptions/rdm_663a1b9c8e4f2a0012abcd34
code:
type: string
description: A machine readable code that describes the specific error condition.
enum:
- bad_request
- unauthorized
- missing_authorization
- resource_not_found
- resource_already_exists
- conflict
- invalid_state_transition
- idempotency_conflict
- operation_not_allowed
- provider_error
- service_unavailable
- request_timeout
- too_many_requests
- internal_server_error
example: resource_not_found
operation_type:
type: string
description: Type of operation recorded on the redemption.
enum:
- reserve
- confirm
operation_status:
type: string
description: Outcome of an individual operation.
enum:
- succeeded
- failed
examples:
full_value_redeem:
summary: Full value redeem (amount omitted)
description: >
Omit `amount` and `currency` to redeem the voucher's full value. The
provider resolves the value and the response returns the redeemed amount
and currency.
value:
type: vouchers.one_voucher
source:
pin: '1115684091419838'
external_reference: order-2026-0001
confirmed_full_redeem:
summary: Confirmed full redeem (1Voucher)
description: >-
Hold less provider redeems voucher synchronously for the full requested
amount.
value:
amount: 1900
currency: ZAR
type: vouchers.one_voucher
source:
pin: '1115684091419838'
external_reference: order-2026-0001
confirmed_1voucher_partial_redeem:
summary: Confirmed 1Voucher partial redeem
description: >-
Customer redeems less than the full voucher value. 1Voucher issues a
change voucher for the remainder.
value:
amount: 6000
currency: ZAR
type: vouchers.one_voucher
source:
pin: '1115684091419838'
external_reference: order-2026-0001
confirmed_blu_partial_redeem:
summary: Confirmed Blu partial redeem
description: >-
Customer redeems less than the full voucher value. Blu issues a
replacement voucher without an explicit amount.
value:
amount: 2000
currency: ZAR
type: vouchers.blu
source:
token: 8276 8409 4119 1701
external_reference: order-2026-blu-0001
failed_voucher_already_used:
summary: Failed (voucher already used)
description: >-
Hold less provider rejects the voucher synchronously. HTTP 201 with
`status: failed`.
value:
amount: 1900
currency: ZAR
type: vouchers.one_voucher
source:
pin: '1115684091419838'
external_reference: order-2026-0001
full_value_redeem_response:
summary: Confirmed full value redemption (amount resolved by provider)
value:
id: rdm_6a0d5c7fe182228a6c64cb78
status: confirmed
version: 3
type: vouchers.one_voucher
provider_reference:
serial_number: '20260520082514335162'
amount: 6000
reserved_amount: 6000
redeemed_amount: 6000
reversed_amount: 0
currency: ZAR
operations:
- id: mpd2156u_7cwvqp5m
type: reserve
status: succeeded
amount: 6000
provider_reference:
pin: '1115684091419838'
created_at: '2026-05-20T08:25:01.014Z'
- id: mpd2185c_vz0wyx10
type: confirm
status: succeeded
amount: 6000
provider_reference:
serial_number: '20260520082514335162'
created_at: '2026-05-20T08:25:14.248Z'
related_ids: []
external_reference: order-2026-0001
created_at: '2026-05-20T08:24:56.501Z'
updated_at: '2026-05-20T08:25:14.249Z'
confirmed_full_redeem_response:
summary: Confirmed redemption (voucher consumed)
value:
id: rdm_6a0d5c7fe182228a6c64cb78
status: confirmed
version: 3
type: vouchers.one_voucher
provider_reference:
serial_number: '20260520082514335162'
amount: 1900
reserved_amount: 1900
redeemed_amount: 1900
reversed_amount: 0
currency: ZAR
operations:
- id: mpd2156u_7cwvqp5m
type: reserve
status: succeeded
amount: 1900
provider_reference:
pin: '1115684091419838'
created_at: '2026-05-20T08:25:01.014Z'
- id: mpd2185c_vz0wyx10
type: confirm
status: succeeded
amount: 1900
provider_reference:
serial_number: '20260520082514335162'
created_at: '2026-05-20T08:25:14.248Z'
related_ids: []
external_reference: order-2026-0001
created_at: '2026-05-20T08:24:56.501Z'
updated_at: '2026-05-20T08:25:14.249Z'
confirmed_1voucher_partial_redeem_response:
summary: Confirmed 1Voucher partial redeem (change voucher issued)
description: >-
Customer redeemed R60 of a R100 voucher. 1Voucher issued a change
voucher for the remainder.
value:
id: rdm_6a0d5c7fe182228a6c64cb78
status: confirmed
version: 3
type: vouchers.one_voucher
provider_reference:
serial_number: '20260520082514335162'
amount: 6000
redeemed_amount: 6000
reversed_amount: 0
currency: ZAR
source:
pin: '1115684091419838'
operations:
- id: mpd2156u_7cwvqp5m
type: confirm
status: succeeded
amount: 6000
provider_reference:
serial_number: '20260520082514335162'
created_at: '2026-05-20T08:25:14.248Z'
change_voucher:
pin: '2226897234561029'
serial_number: '20260520082514998877'
amount: 4000
expires_at: '2027-05-20T00:00:00Z'
status: issued
related_ids: []
external_reference: order-2026-0001
created_at: '2026-05-20T08:24:56.501Z'
updated_at: '2026-05-20T08:25:14.249Z'
confirmed_blu_partial_redeem_response:
summary: Confirmed Blu partial redeem (change voucher issued)
description: >-
Customer redeemed less than the full voucher value. Blu issued a
replacement voucher without an explicit amount. Caller can issue a
stored value lookup against `change_voucher.pin` for the residual
balance.
value:
id: rdm_7c1b9e08f2349a0d12cdef98
status: confirmed
version: 3
type: vouchers.blu
provider_reference:
token: 8276 8409 4119 1701
reference: '0902834592'
serial_number: BL016C1E46AD2768
amount: 2000
redeemed_amount: 2000
reversed_amount: 0
currency: ZAR
source:
token: 8276 8409 4119 1701
operations:
- id: mpd2186u_7gqv0p5m
type: confirm
status: succeeded
amount: 2000
provider_reference:
token: 8276 8409 4119 1701
reference: '0902834592'
serial_number: BL016C1E46AD2768
created_at: '2026-05-23T10:00:00.000Z'
change_voucher:
pin: 8276 8409 4119 1701
serial_number: BL016C1E46AD2768
expires_at: '2019-01-09T14:07:41'
reference: '0902834592'
barcode: 6009802367896
product_name: Chat 4 Change Vodacom Voucher
product_instructions: TO RECHARGE DIAL:*130*TOKEN#
product_help: 'Customer Care: SMS ''help'' to 30505.'
customer_message: No Refunds. Vouchers cannot be reprinted
related_ids: []
external_reference: order-2026-blu-0001
created_at: '2026-05-23T09:59:50.000Z'
updated_at: '2026-05-23T10:00:00.000Z'
failed_voucher_already_used_response:
summary: Failed (voucher already used)
description: >
HTTP 200 with a `failed` status. The transition itself succeeded (the
attempt is recorded). The underlying provider call did not. Clients
should inspect `status` and `last_error`, not the HTTP code.
value:
id: rdm_6a0d5c7fe182228a6c64cb78
status: failed
version: 2
type: vouchers.one_voucher
provider_reference:
pin: '1115684091419838'
amount: 1900
reserved_amount: 1900
reversed_amount: 0
currency: ZAR
operations:
- id: mpd2156u_7cwvqp5m
type: reserve
status: succeeded
amount: 1900
provider_reference:
pin: '1115684091419838'
created_at: '2026-05-20T08:25:01.014Z'
- id: mpd64fjl_z4gy9pw0
type: confirm
status: failed
amount: 1900
provider_reference:
pin: '1115684091419838'
error:
error_code: BAD_REQUEST
message: >-
The voucher you have entered has already been used, please use
another voucher pin.
created_at: '2026-05-20T08:25:14.248Z'
last_error:
error_code: BAD_REQUEST
message: >-
The voucher you have entered has already been used, please use
another voucher pin.
related_ids: []
external_reference: order-2026-0001
created_at: '2026-05-20T08:24:56.501Z'
updated_at: '2026-05-20T08:25:14.249Z'
responses:
bad_request:
description: Validation failed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/problem_detail'
example:
type: https://api.momentco.io/problems/bad_request
title: Bad Request
status: 400
detail: amount must be a positive integer
instance: /collect/redemptions
code: bad_request
unauthorized:
description: Authentication required.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/problem_detail'
example:
type: https://api.momentco.io/problems/unauthorized
title: Unauthorized
status: 401
detail: The API key provided is invalid.
instance: /collect/redemptions
code: unauthorized
idempotency_conflict:
description: Same `Idempotency-Key` reused with a different request body.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/problem_detail'
example:
type: https://api.momentco.io/problems/idempotency_conflict
title: Idempotency Key Conflict
status: 409
detail: Idempotency-Key reused with different request body
instance: /collect/redemptions
code: idempotency_conflict
internal_server_error:
description: Unexpected server error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/problem_detail'
example:
type: https://api.momentco.io/problems/internal_server_error
title: Internal Server Error
status: 500
detail: An unexpected error occurred. Please try again later.
instance: /collect/redemptions
code: internal_server_error
securitySchemes:
bearer_auth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Authentication using Bearer tokens. Include your API key in the
Authorization header.
**Key Types:**
- **Test Keys**: `sk_test_*` for development and testing
- **Live Keys**: `sk_*` for production environments
- **Public Keys**: `pk_test_*` or `pk_*` for client-side operations
> 📩 **Need access?** [Contact Support](/documentation/support) to
request your API keys.
**Usage:**
```http
Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc
```
````