API reference · Cards & gift cards

Gift card orders

GET/gift-card/orderList your gift card orders
POST/gift-card/orderPlace a bulk gift card order
DELETE/gift-card/order/{reference}Close an order and reclaim what nobody took
GET/gift-card/order/{reference}Fetch one gift card order
POST/gift-card/order/{reference}/approveApprove an order above the threshold
GET/gift-card/order/{reference}/lineRead an order's lines, issued and failed

GET List your gift card orders

GET /gift-card/order

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Query parameters

Name	Default
`page`	0
`size`	20

Example

Response: GenericResponseListGiftCardOrderResponse

curl -X GET "https://api.bridgemoni.com/gift-card/order?page=value&size=20" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": [
    {
      "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "buyerUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "currencyCode": "string",
      "totalFaceValue": 0,
      "totalCharged": 0,
      "status": "DRAFT",
      "approvalRequired": true,
      "approvedBy": "string",
      "approvedDateTime": "2026-09-25T10:00:00Z",
      "campaignReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "costCentre": "string",
      "scheduledForDateTime": "2026-09-25T10:00:00Z",
      "lineCount": 0,
      "linesIssued": 0,
      "linesFailed": 0,
      "reclaimedAmount": 0,
      "failures": [
        {
          "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
          "lineNumber": 0,
          "productReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
          "unitFaceValue": 0,
          "recipientName": "Ada Okafor",
          "status": "PENDING",
          "failureReason": "Recipient msisdn is not valid"
        }
      ],
      "createdDateTime": "2026-09-25T10:00:00Z"
    }
  ],
  "description": "Gift card orders retrieved successfully"
}

Responses

Status	When
`200`	Gift card orders retrieved successfully

POST Place a bulk gift card order

POST /gift-card/order

Every line is validated before any money moves. The order funds the programme's float once, then each line is issued in its own transaction - so three bad recipients in a five-thousand-line campaign report as three failures and the other 4,997 cards exist. Their value is returned to the buyer straight away rather than left in the float backing no card.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Idempotency-Key`	Reuse the same value on every retry of this request
`Content-Type`	application/json

Example

Request body: CreateGiftCardOrderRequest · Response: GenericResponseGiftCardOrderResponse

curl -X POST "https://api.bridgemoni.com/gift-card/order" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "campaignReference": "Q4-WINBACK",
  "costCentre": "MKT-204",
  "scheduledForDateTime": "2026-09-25T10:00:00Z",
  "lines": [
    {
      "lineNumber": 1,
      "productReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "unitFaceValue": 10000.0,
      "recipientName": {
        "name": "string"
      },
      "recipientMsisdn": "string",
      "recipientEmailAddress": "string",
      "deliveryChannel": "EMAIL",
      "scheduledForDateTime": "2026-09-25T10:00:00Z",
      "personalMessage": "string"
    }
  ]
}'

{
  "campaignReference": "Q4-WINBACK",
  "costCentre": "MKT-204",
  "scheduledForDateTime": "2026-09-25T10:00:00Z",
  "lines": [
    {
      "lineNumber": 1,
      "productReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "unitFaceValue": 10000.0,
      "recipientName": {
        "name": "string"
      },
      "recipientMsisdn": "string",
      "recipientEmailAddress": "string",
      "deliveryChannel": "EMAIL",
      "scheduledForDateTime": "2026-09-25T10:00:00Z",
      "personalMessage": "string"
    }
  ]
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "buyerUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "currencyCode": "string",
    "totalFaceValue": 0,
    "totalCharged": 0,
    "status": "DRAFT",
    "approvalRequired": true,
    "approvedBy": "string",
    "approvedDateTime": "2026-09-25T10:00:00Z",
    "campaignReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "costCentre": "string",
    "scheduledForDateTime": "2026-09-25T10:00:00Z",
    "lineCount": 0,
    "linesIssued": 0,
    "linesFailed": 0,
    "reclaimedAmount": 0,
    "failures": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "lineNumber": 0,
        "productReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "unitFaceValue": 0,
        "recipientName": "Ada Okafor",
        "status": "PENDING",
        "failureReason": "Recipient msisdn is not valid"
      }
    ],
    "createdDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Gift card order placed successfully"
}

Responses

Status	When
`200`	Gift card order placed successfully

DELETE Close an order and reclaim what nobody took

DELETE /gift-card/order/{reference}

Returns the value of every card still unclaimed and unspent. A card somebody has claimed or part-redeemed is not reclaimable - from that point the value is theirs, whoever paid for it.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Path parameters

Name
`reference`

Example

Request body: BlockGiftCardRequest · Response: GenericResponseGiftCardOrderResponse

curl -X DELETE "https://api.bridgemoni.com/gift-card/order/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string"
}'

{
  "reason": "string"
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "buyerUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "currencyCode": "string",
    "totalFaceValue": 0,
    "totalCharged": 0,
    "status": "DRAFT",
    "approvalRequired": true,
    "approvedBy": "string",
    "approvedDateTime": "2026-09-25T10:00:00Z",
    "campaignReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "costCentre": "string",
    "scheduledForDateTime": "2026-09-25T10:00:00Z",
    "lineCount": 0,
    "linesIssued": 0,
    "linesFailed": 0,
    "reclaimedAmount": 0,
    "failures": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "lineNumber": 0,
        "productReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "unitFaceValue": 0,
        "recipientName": "Ada Okafor",
        "status": "PENDING",
        "failureReason": "Recipient msisdn is not valid"
      }
    ],
    "createdDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Gift card order closed successfully"
}

Responses

Status	When
`200`	Gift card order closed successfully

GET Fetch one gift card order

GET /gift-card/order/{reference}

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: GenericResponseGiftCardOrderResponse

curl -X GET "https://api.bridgemoni.com/gift-card/order/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "buyerUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "currencyCode": "string",
    "totalFaceValue": 0,
    "totalCharged": 0,
    "status": "DRAFT",
    "approvalRequired": true,
    "approvedBy": "string",
    "approvedDateTime": "2026-09-25T10:00:00Z",
    "campaignReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "costCentre": "string",
    "scheduledForDateTime": "2026-09-25T10:00:00Z",
    "lineCount": 0,
    "linesIssued": 0,
    "linesFailed": 0,
    "reclaimedAmount": 0,
    "failures": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "lineNumber": 0,
        "productReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "unitFaceValue": 0,
        "recipientName": "Ada Okafor",
        "status": "PENDING",
        "failureReason": "Recipient msisdn is not valid"
      }
    ],
    "createdDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Gift card order retrieved successfully"
}

Responses

Status	When
`200`	Gift card order retrieved successfully

POST Approve an order above the threshold

POST /gift-card/order/{reference}/approve

Funds the order and issues its lines. The approver must be somebody other than the buyer - issuing cards nobody paid for is the insider vector this catches, and the check is explicit rather than left to a permission difference.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: GenericResponseGiftCardOrderResponse

curl -X POST "https://api.bridgemoni.com/gift-card/order/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/approve" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "buyerUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "currencyCode": "string",
    "totalFaceValue": 0,
    "totalCharged": 0,
    "status": "DRAFT",
    "approvalRequired": true,
    "approvedBy": "string",
    "approvedDateTime": "2026-09-25T10:00:00Z",
    "campaignReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "costCentre": "string",
    "scheduledForDateTime": "2026-09-25T10:00:00Z",
    "lineCount": 0,
    "linesIssued": 0,
    "linesFailed": 0,
    "reclaimedAmount": 0,
    "failures": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "lineNumber": 0,
        "productReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "unitFaceValue": 0,
        "recipientName": "Ada Okafor",
        "status": "PENDING",
        "failureReason": "Recipient msisdn is not valid"
      }
    ],
    "createdDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Gift card order approved successfully"
}

Responses

Status	When
`200`	Gift card order approved successfully

GET Read an order's lines, issued and failed

GET /gift-card/order/{reference}/line

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: GenericResponseListGiftCardOrderLineResponse

curl -X GET "https://api.bridgemoni.com/gift-card/order/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/line" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": [
    {
      "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "lineNumber": 0,
      "productReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "unitFaceValue": 0,
      "recipientName": "Ada Okafor",
      "status": "PENDING",
      "failureReason": "Recipient msisdn is not valid"
    }
  ],
  "description": "Gift card order lines retrieved successfully"
}

Responses

Status	When
`200`	Gift card order lines retrieved successfully

Generated from the OpenAPI document. Branch on the HTTP status: there is no machine-readable error code on the wire. Errors