Update Transaction Status (Banks API)

Banks use this endpoint to update transaction statuses after processing customer approval requests.

Endpoint

POST /api/v1/banks/debit-transactions/:uuid/update

Authentication

Requires a valid Bearer token in the Authorization header.

Authorization: Bearer YOUR_BANK_API_TOKEN

Path Parameters

Parameter	Type	Required	Description
uuid	string	Yes	Unique transaction identifier (UUID format)

Request Body

Field	Type	Required	Description
status	string	Yes	New transaction status (see valid statuses below)
bank_reference	string	Yes	Your internal reference/transaction ID
approval_method	string	No	How customer approved: "ussd", "mobile_api", or "web"
error_message	string	Conditional	Required when status is "failed"
fee	decimal	No	Total fee charged for the transaction
metadata	object	No	Additional data to attach (merged with existing metadata)

Valid Status Values

Status	Description	From Status	Required Fields
processing	Customer approved, processing payment	pending	bank_reference, approval_method
completed	Payment successfully completed	pending, processing	bank_reference
failed	Transaction failed or declined	pending, processing	bank_reference, error_message

Status Restrictions: Banks cannot set status to processing via this endpoint. The processing status is set automatically by FLUID Network when the transaction is forwarded to the bank.

Valid Approval Methods

• ussd - Customer approved via USSD prompt
• mobile_api - Customer approved via mobile banking app
• web - Customer approved via web interface

Example Request

# Completed transaction
curl --request POST \
  --url https://api.fluid-network.com/api/v1/banks/debit-transactions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/update \
  --header 'Authorization: Bearer YOUR_BANK_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "completed",
    "bank_reference": "BNK987654321",
    "approval_method": "ussd",
    "fee": 0.50
  }'

# Failed transaction
curl --request POST \
  --url https://api.fluid-network.com/api/v1/banks/debit-transactions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/update \
  --header 'Authorization: Bearer YOUR_BANK_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "failed",
    "bank_reference": "BNK987654321",
    "approval_method": "ussd",
    "error_message": "Insufficient funds in customer account"
  }'

Response

Success Response

Status Code: 200 OK

{
  "success": true,
  "data": {
    "id": 12345,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reference": "FLU123456789",
    "status": "completed",
    "approval_method": "ussd",
    "bank_reference": "BNK987654321",
    "error_message": null,
    "fee": "0.50",
    "updated_at": "2025-01-05T12:05:00Z"
  },
  "meta": {
    "timestamp": "2025-01-05T12:05:00Z",
    "request_id": "xyz-789",
    "api_version": "v1"
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the update was successful
data.id	integer	Internal transaction database ID
data.uuid	string	Unique transaction identifier
data.reference	string	FLUID Network transaction reference
data.status	string	Updated transaction status
data.approval_method	string	How customer approved the transaction
data.bank_reference	string	Bank's internal reference number
data.error_message	string	Error details (null if no error)
data.fee	string	Total fee as decimal string
data.updated_at	string	Last update timestamp (ISO 8601)

Error Responses

Transaction Not Found

Status Code: 404 Not Found

{
  "success": false,
  "error": {
    "code": 1404,
    "message": "Transaction not found",
    "category": "transactions"
  },
  "details": "Transaction not found",
  "meta": {
    "timestamp": "2025-01-05T12:05:00Z",
    "request_id": "xyz-789"
  }
}

Common Causes:

• Invalid UUID format
• Transaction doesn't exist
• Transaction belongs to a different bank

Validation Error

Status Code: 422 Unprocessable Content

{
  "success": false,
  "error": {
    "code": 1007,
    "message": "Validation failed",
    "category": "validation",
    "details": {
      "status": ["cannot transition from completed to failed"],
      "error_message": ["is required when status is 'failed'"]
    }
  }
}

Common Validation Errors:

• Invalid status transition (e.g., completed → failed)
• Missing required fields (bank_reference, error_message for failed)
• Invalid approval method value
• Attempting to set processing status via callback
• Fee is negative

Invalid Status Transition

Status Code: 422 Unprocessable Content

{
  "success": false,
  "error": {
    "code": 3001,
    "message": "Invalid status transition",
    "category": "transactions"
  }
}

Rate Limit Exceeded

Status Code: 429 Too Many Requests

{
  "success": false,
  "error": {
    "code": 1455,
    "message": "Rate limit exceeded for bank",
    "category": "security"
  }
}

Status Transition Flow

Best Practices

1. Always Provide Bank Reference

Always include your internal bank reference number in status updates. This is required for reconciliation and audit purposes.

2. Include Detailed Error Messages

When marking a transaction as failed, provide specific error messages rather than generic ones. Good error messages include details like "Insufficient funds: Customer balance GHS 50.00, required GHS 100.00" instead of just "Failed".

3. Set Approval Method

Track how customers approved transactions using the approval_method field (ussd, mobile_api, or web). This helps with analytics and customer support.

4. Implement Retry Logic

Implement retry logic with exponential backoff for network and server errors. Do not retry validation errors (422 status). Use delays between retries (1 second, 2 seconds, 3 seconds, etc.) and limit to 3 attempts maximum.

5. Handle Idempotency

Updates with the same status are idempotent. Calling the endpoint multiple times with the same status is safe and won't cause duplicate processing.

Common Integration Patterns

Pattern 1: USSD Flow

1. Fetch pending transaction from FLUID
2. Send USSD prompt to customer with transaction details
3. Wait for customer to approve via USSD
4. Update transaction status to "completed" with bank reference, approval method "ussd", and calculated fee

Pattern 2: Mobile API Flow

1. Fetch pending transaction from FLUID
2. Send push notification to customer's mobile banking app
3. Wait for customer to approve in app
4. Update transaction status to "completed" with bank reference, approval method "mobile_api", fee, and optional metadata (app version, device ID)

Pattern 3: Timeout Handling

Set a timeout (e.g., 5 minutes) for customer approval. If the transaction is still in pending or processing status after the timeout expires, mark it as failed with error message "Customer did not approve within 5 minutes".

Webhooks & Notifications

When a transaction reaches a final status (completed, failed), FLUID automatically:

1. Sends webhook to payment partner (if configured)
2. Creates transaction event in audit log
3. Updates settlement batch (for completed transactions)

Payment partners will receive:

POST https://partner-webhook-url.com/webhooks

{
  "event": "transaction.completed",
  "data": {
    "reference": "FLU123456789",
    "status": "completed",
    "amount": 100.00,
    "currency": "GHS",
    "partner_reference": "partner_tx_123456",
    "timestamp": "2025-01-05T12:05:00Z"
  }
}

Rate Limits

• Production: 30 requests per minute per bank
• Sandbox: 10 requests per minute per bank

Note: Rate limits apply per bank API token. If you need higher limits, contact FLUID support.

Security Considerations

1. Never expose UUIDs publicly - They're sensitive identifiers
2. Validate status transitions before calling this endpoint
3. Store bank_reference before making the update
4. Log all status updates for audit trails
5. Implement webhook signature verification for incoming transactions

Troubleshooting

"Transaction not found" Error

Cause: UUID doesn't exist or belongs to another bank

Solution:

• Verify UUID format is correct
• Check transaction belongs to your bank
• Ensure transaction was fetched from the correct endpoint

"Invalid status transition" Error

Cause: Attempting invalid state change (e.g., completed → failed)

Solution:

• Check current transaction status first
• Review valid transition flow diagram above
• Don't retry failed transitions with same status

"Validation failed: error_message required" Error

Cause: Setting status to "failed" without error_message

Solution: Always include error_message field when setting status to "failed". Provide a specific reason for the failure (e.g., "Insufficient funds", "Customer declined", "Account blocked").

Next Steps

• Fetch pending transactions
• Understand transaction flow
• Test in sandbox