Skip to main content
Every remittance transaction moves through a series of well-defined states from creation to completion. Understanding these states helps you build robust integrations and provide clear user feedback.

​
Active States

Description: Transaction created, awaiting payment from userWhat Happens:
  • Transaction reference generated
  • User redirected to payment page
  • Timer starts for quote validity
User Actions Available:
  • Complete payment via card or open banking
  • Cancel the transaction
  • View transaction details
Next Possible States:
  • VERIFYING - Payment successfully received
  • CANCELLED - User cancelled before payment
  • EXPIRED - Payment not completed within 10 minutes
Description: Payment received, undergoing compliance checksWhat Happens:
  • AML/CFT screening initiated
  • Sanctions list checking
  • Risk score calculation
  • PEP screening (if applicable)
  • Transaction pattern analysis
System Actions:
  • Automated compliance checks run
  • Manual review triggered if flagged
  • Compliance team notified (if needed)
Next Possible States:
  • PAID - All checks passed, funds disbursed
  • PENDING_REFUND - Compliance or payment after transaction expiration
  • FAILED_TO_DELIVER - Delivery issues detected
Most transactions (95%+) pass automated checks and move to PAID within 0-2 minutes.
Description: Delivery attempt failed, automatic retry in progressCommon Causes:
  • Invalid or closed bank account
  • Inactive mobile money account
  • Network timeout or provider downtime
  • Incorrect account details
  • Beneficiary name mismatch
System Actions:
  • Exponential backoff between retries
  • Notify compliance team after 2nd failure
  • Contact user for corrections if needed
Next Possible States:
  • PAID - Retry successful
  • PENDING_REFUND
Contact your customer to verify beneficiary details if this status persists.
Description: Refund initiated, processing back to senderTriggers:
  • Compliance rejection (AML/sanctions)
  • Delivery failure after max retries
  • Customer dispute (within refund window)
  • Technical error requiring reversal
What Happens:
  • Refund request submitted to payment processor
  • Original payment method receives credit
  • Refund notification sent to user
  • Transaction marked for closure
Refund Amount:
  • Full transaction amount (send amount)
  • All fees included
  • Same payment method as original
Next Possible State:
  • REFUNDED - Refund completed successfully

​
State Transition Triggers

Understanding what causes state changes helps you build better error handling.
From StateTo StateTriggerAction Required
WAITING_TO_PAYVERIFYINGPayment successfulAutomatic
WAITING_TO_PAYCANCELLEDUser cancelledNone
WAITING_TO_PAYEXPIRED10 min timeoutRequest new quote
From StateTo StateTriggerAction Required
VERIFYINGPAIDAll checks passedNone - Automatic
VERIFYINGPENDING_REFUNDCompliance/Payment failedContact support
VERIFYINGFAILED_TO_DELIVERDelivery issueCheck beneficiary details

​
Refund Transitions

From StateTo StateTriggerAction Required
PENDING_REFUNDREFUNDEDRefund processedAutomatic

Webhook Configuration

Learn how to set up webhooks for real-time updates

​
Common Scenarios

​
Scenario 1: Successful Transaction

​
Scenario 2: Compliance Rejection

​
Scenario 3: Delivery Failure with Recovery

​
API Reference

Transaction Status Endpoint

View complete API documentation for tracking transaction status

Beneficiary Lifecycle

Learn how to create and validate beneficiaries

​
Quote Calculator Integration

You can easily integrate a Quote Calculator into your own website or dashboard using our ready-made widget. This handles flag updates, country selection, and real-time exchange rates automatically.

​
Integration Guide

Add the following code to your HTML page where you want the widget to appear:
1

Add the Container

Place this div in your layout. You can customize the initial values using data- attributes.
<div 
  id="fincode-remittance-widget" 
  data-default-send-country="GBR" 
  data-default-receive-country="NGA"
  data-button-text="Send Now"
  data-button-color="#000000"
></div>
2

Include the Script

Add this script tag at the bottom of your <body> tag.
<script src="https://quote.trillionclues.dev/widget.js"></script>

​
Configuration Options

Customize the widget behavior by adding these attributes to the container div:
AttributeDescriptionDefault
data-default-send-countryISO3 Code for the default sending countryGBR
data-default-receive-countryISO3 Code for the default receiving countryNGA
data-default-amountInitial amount for the “Send” field100
data-button-textText displayed on the main buttonSend Money Now
data-button-colorColor code for the action button#000000
The widget is fully responsive and will adapt to the width of its parent container. For the best experience, place it in a column between 350px and 500px wide. To see the full usage guide, follow this link https://fxquote-widget.vercel.app/index.html