Documentation

Western Union Integration Guide

Integration Guide for approved partners to now offer Western Union Cash Pickup Method

Western Union Widget - Integration Guide (V1 Colombia)

Overview

The Western Union Widget allows partners to embed an end-to-end Crypto-to-Cash payout experience powered by Western Union.

The widget receives transaction information through URL parameters, guides the user through identity verification (KYC), displays real-time exchange rates and fees, and ultimately generates a Western Union cash pickup transaction with an MTCN for withdrawal.

The solution is designed to be launched from external applications, customer portals, dashboards, wallets, or consumer-facing platforms.

High-Level Flow

Partner Application
       │
       ▼
Launch Widget
       │
       ▼
KYC Validation
       │
       ▼
Review Transaction
       │
       ▼
Payment Confirmation
       │
       ▼
Crypto Deposit (Transaction Sign)
       │
       ▼
Western Union Processing
       │
       ▼
MTCN Generated
       │
       ▼
Cash Pickup Available

Environment URLs

EnvironmentURL
Productionhttps://wu-widget.alfredpay.app/
Staginghttps://wu-widget-stg.alfredpay.app/

Widget URL

The widget is invoked through a URL containing all required transaction parameters.

Example

https://wu-widget-stg.alfredpay.app/
?country=COP
&cryptoAmount=100
&cryptoCurrency=USDC
&depositAddress=53xbcPq7NaVNyRmNBjH7A8UUnXRPcPUXdiUdD2tDvzDQ
&redirectUrl=https://www.partner-site.com
&walletAddress=0x8f3a2b9c4d6e1f0a7b5c9d2e4f6a8b1c3d5e7f13
&token=JWT_TOKEN

Note: The JWT_TOKEN is generated using the Alfred API endpoint:

POST /api/app/front-link

using the client's API_KEY provided during onboarding.

URL Parameters

ParameterRequiredDescription
countryYesDestination country code
cryptoAmountYesAmount of cryptocurrency to be paid
cryptoCurrencyYesCryptocurrency used for payment
depositAddressYesWallet address where funds must be deposited
walletAddressYesCustomer wallet address
tokenYesJWT authorization token
redirectUrlYesURL to redirect after completion

Supported Parameters

country

ISO country code.

Examples

COP
MXN
ARS
PEN
CLP

cryptoAmount

Amount sent by the user.

Example

1000

cryptoCurrency

Supported crypto asset.

Examples

USDC
USDT

depositAddress

Unique wallet generated for the transaction.

Example

53xbcPq7NaVNyRmNBjH7A8UUnXRPcPUXdiUdD2tDvzDQ

walletAddress

Origin wallet from the customer.

Example

0x8f3a2b9c4d6e1f0a7b5c9d2e4f6a8b1c3d5e7f13

redirectUrl

Destination URL after transaction completion.

Example

https://partner-domain.com/transaction-completed

token

JWT token generated by Alfred Backend.

Authentication

The widget validates:

  • JWT signature
  • Expiration date
  • Client ownership
  • Business ownership

Invalid or expired tokens will prevent widget access.

KYC Flow

Before payment confirmation, the user must complete identity verification.

Collected Information

Identification

  • ID Type
  • Country
  • State / Region

Personal Information

  • Full Name
  • Date of Birth
  • Address
  • Phone Number

This information is required for Western Union compliance processes.

Transaction Review Screen

The review page displays:

Amount Sent

1000 USDC

Amount Received

3,633,720 COP

Live Exchange Rate

1 USDC = 3,633.72 COP

Fees

  • Western Union Fee
  • Service Fee
  • Total Fees

Payment Method

Example:

Coinbase Wallet

Payment Processing

After confirmation:

  1. User sends crypto to the provided deposit address using Partner Transaction Signing.
  2. Blockchain confirmation is detected.
  3. Transaction status changes to Processing.
  4. Western Union payout is initiated.
  5. MTCN is generated.

Successful Transaction

The widget displays:

Transferencia enviada
Ready for Pickup

Including:

  • MTCN
  • Pickup Instructions
  • Nearby Pickup Locations

Cash Pickup Information

The widget provides:

MTCN

1251687118

Pickup Instructions

  1. Visit any Western Union branch.
  2. Provide the MTCN.
  3. Present a valid government-issued ID.
  4. Receive funds.

Nearby Locations

The widget can display:

  • Interactive map
  • Nearest Western Union agents
  • Distance
  • Business hours

Cancellation Flow

Transactions may be cancelled before completion.

Result

Transaction Cancelled

Refund information is displayed.

Example

Refund will be processed within 7 days.

Redirect Behavior

Upon successful completion, the widget redirects the user to the provided redirectUrl.

Example

https://partner-domain.com/transaction-completed

Recommended Query Parameters

status=success
transactionId=xxxxx
mtcn=1251687118

Example:

https://partner-domain.com/transaction-completed
?status=success
&transactionId=xxxxx
&mtcn=1251687118

Transaction Statuses

StatusDescription
PendingAwaiting payment
ProcessingBlockchain confirmation received
ReadyForPickupMTCN generated
CompletedFunds collected
CancelledTransaction cancelled
ExpiredPayment window expired
FailedProcessing failure

Error Handling

The widget may return any of the transaction statuses listed above depending on the transaction lifecycle.

Partners should monitor and reconcile transactions using:

  • transactionId
  • MTCN
  • Redirect callbacks
  • Backend transaction records

Security Recommendations

Partners should:

  • Generate short-lived JWT tokens.
  • Use HTTPS exclusively.
  • Never expose backend secrets.
  • Validate callback responses.
  • Log transaction identifiers for reconciliation.

Integration Checklist

  • Generate JWT via /api/app/front-link
  • Launch widget with required URL parameters
  • Provide unique deposit address
  • Handle redirect callback
  • Store transaction identifiers
  • Reconcile MTCN values
  • Monitor transaction statuses
  • Validate successful transaction completion
  • Implement secure token generation and rotation