UMA as a Service (UMAaaS) API (2025-05-15)

Retrieve the current platform configuration

Update the platform configuration settings

Register a new user in the system with UMA address and bank account information

Retrieve a list of users with optional filtering parameters. Returns all users that match the specified filters. If no filters are provided, returns all users (paginated).

Retrieve a user by their system-generated ID

Update a user's metadata by their system-generated ID

Delete a user by their system-generated ID

Upload a CSV file containing user information for bulk creation. The CSV file should follow a specific format with required and optional columns based on user type.

CSV Format

The CSV file should have the following columns:

Required columns for all users:

• umaAddress: The user's UMA address (e.g., $john.doe@uma.domain.com)
• platformUserId: Your platform's unique identifier for the user
• userType: Either "INDIVIDUAL" or "BUSINESS"

Required columns for individual users:

• fullName: Individual's full name
• birthDate: Date of birth in YYYY-MM-DD format
• addressLine1: Street address line 1
• city: City
• state: State/Province/Region
• postalCode: Postal/ZIP code
• country: Country code (ISO 3166-1 alpha-2)
• accountType: Bank account type (CLABE, US_ACCOUNT, PIX, IBAN)
• accountNumber: Bank account number
• bankName: Name of the bank

Required columns for business users:

• businessLegalName: Legal name of the business
• addressLine1: Street address line 1
• city: City
• state: State/Province/Region
• postalCode: Postal/ZIP code
• country: Country code (ISO 3166-1 alpha-2)
• accountType: Bank account type (CLABE, US_ACCOUNT, PIX, IBAN)
• accountNumber: Bank account number
• bankName: Name of the bank

Optional columns for all users:

• addressLine2: Street address line 2
• platformAccountId: Your platform's identifier for the bank account
• description: Optional description for the user

Optional columns for individual users:

• email: User's email address

Optional columns for business users:

• businessRegistrationNumber: Business registration number
• businessTaxId: Tax identification number

Additional required columns based on account type:

For US_ACCOUNT:

• routingNumber: ACH routing number (9 digits)
• accountCategory: Either "CHECKING" or "SAVINGS"

For CLABE:

• clabeNumber: 18-digit CLABE number

For PIX:

• pixKey: PIX key value
• pixKeyType: Type of PIX key (CPF, CNPJ, EMAIL, PHONE, RANDOM)

For IBAN:

• iban: International Bank Account Number
• swiftBic: SWIFT/BIC code (8 or 11 characters)

See the UserBankAccountInfo and UserInfo schemas for more details on the required and optional fields.

Example CSV

umaAddress,platformUserId,userType,fullName,birthDate,addressLine1,city,state,postalCode,country,accountType,accountNumber,bankName,platformAccountId,businessLegalName,routingNumber,accountCategory
john.doe@uma.domain.com,user123,INDIVIDUAL,John Doe,1990-01-15,123 Main St,San Francisco,CA,94105,US,US_ACCOUNT,123456789,Chase Bank,chase_primary_1234,,222888888,SAVINGS
acme@uma.domain.com,biz456,BUSINESS,,,400 Commerce Way,Austin,TX,78701,US,US_ACCOUNT,987654321,Bank of America,boa_business_5678,Acme Corp,121212121,CHECKING

The upload process is asynchronous and will return a job ID that can be used to track progress. You can monitor the job status using the /users/bulk/jobs/{jobId} endpoint.

Retrieve the current status and results of a bulk user import job. This endpoint can be used to track the progress of both CSV uploads.

The response includes:

• Overall job status
• Progress statistics
• Detailed error information for failed entries
• Completion timestamp when finished

Retrieve detailed information about a specific transaction

Retrieve a paginated list of transactions with optional filtering. The transactions can be filtered by user ID, platform user ID, UMA address, date range, status, and transaction type.

Approve a pending incoming payment that was previously acknowledged with a 202 response. This endpoint allows platforms to asynchronously approve payments after async processing.

Reject a pending incoming payment that was previously acknowledged with a 202 response. This endpoint allows platforms to asynchronously reject payments after additional processing.

Lookup a receiving UMA address to determine supported currencies and exchange rates. This endpoint helps platforms determine what currencies they can send to a given UMA address.

Generate a quote for a payment from one UMA address to another. The quote locks in exchange rates and fees for a set period of time and provides payment instructions that can be used to execute the payment.

Depending on the lockedCurrencySide parameter, either the sending amount or receiving amount will be locked.

The returned quote includes payment instructions with the banking details needed to execute the payment and fulfill the quote. These instructions must be followed precisely, including any reference codes provided.

Retrieve a quote by its ID. If the quote has been settled, it will include the transaction ID. This allows clients to track the full lifecycle of a payment from quote creation to settlement.

In the case where a customer is debited but the Lightning payment fails to complete, integrators can retry the payment using this endpoint.

Payments retried with this endpoint will debit from the sender and deliver to the recipient the same amount as the original quote. As UMA as a service does not persist customer PII, retries need to start with a lookup request to retrieve the original quote's recipient counter party data requirements then pass that sender information in the request body. Before calling this endpoint, you should reach out to the UMA as a service team to investigate the underlying issue. As part of resolution, they'll update the transaction to the appropriate state. The quote / transaction to retry must be in a FAILED or REFUNDED state.

This endpoint should only be used for when your account is configured for FBO payments. It triggers funding a quote from your FBO account to initiate payment.

Webhook that is called when an incoming payment is received by a user's UMA address. This endpoint should be implemented by clients of the UMAaas API.

Authentication

The webhook includes a signature in the X-UMAaas-Signature header that allows you to verify that the webhook was sent by UMAaas. To verify the signature:

1. Get the UMAaas public key provided to you during integration
2. Decode the base64 signature from the header
3. Create a SHA-256 hash of the request body
4. Verify the signature using the public key and the hash

If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

Payment Approval Flow

When a transaction has status: "PENDING", this webhook serves as an approval mechanism:

1. The client should check the counterpartyInformation against their requirements
2. To APPROVE the payment synchronously, return a 200 OK response
3. To REJECT the payment, return a 403 Forbidden response with an Error object
4. To request more information, return a 422 Unprocessable Entity with specific missing fields
5. To process the payment asynchronously, return a 202 Accepted response and then call the /transactions/{transactionId}/approve or /transactions/{transactionId}/reject endpoint within 5 seconds. Note that synchronous approval/rejection is preferred where possible.

The UMAaas system will proceed or cancel the payment based on your response.

For transactions with other statuses (COMPLETED, FAILED, REFUNDED), this webhook is purely informational.

Webhook that is called when an outgoing payment's status changes. This endpoint should be implemented by clients of the UMAaas API.

Authentication

The webhook includes a signature in the X-UMAaas-Signature header that allows you to verify that the webhook was sent by UMAaas. To verify the signature:

1. Get the UMAaas public key provided to you during integration
2. Decode the base64 signature from the header
3. Create a SHA-256 hash of the request body
4. Verify the signature using the public key and the hash

If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

This webhook is informational only and is sent when an outgoing payment completes successfully or fails.

Webhook that is sent once to verify your webhook endpoint is correctly set up. This is sent when you configure or update your platform settings with a webhook URL.

Authentication

The webhook includes a signature in the X-UMAaas-Signature header that allows you to verify that the webhook was sent by UMAaas. To verify the signature:

1. Get the UMAaas public key provided to you during integration
2. Decode the base64 signature from the header
3. Create a SHA-256 hash of the request body
4. Verify the signature using the public key and the hash

If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

This webhook is purely for testing your endpoint integration and signature verification.

Webhook that is called when a bulk user upload job completes or fails. This endpoint should be implemented by clients of the UMAaas API.

Authentication

The webhook includes a signature in the X-UMAaas-Signature header that allows you to verify that the webhook was sent by UMAaas. To verify the signature:

1. Get the UMAaas public key provided to you during integration
2. Decode the base64 signature from the header
3. Create a SHA-256 hash of the request body
4. Verify the signature using the public key and the hash

If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

This webhook is sent when a bulk upload job completes or fails, providing detailed information about the results.

Webhook that is called when an invitation is claimed by a user. This endpoint should be implemented by platform clients of the UMAaaS API.

When a user claims an invitation, this webhook is triggered to notify the platform that:

1. The invitation has been successfully claimed
2. The invitee UMA address is now associated with the invitation
3. The invitation status has changed from PENDING to CLAIMED

This allows platforms to:

• Track invitation usage and conversion rates
• Trigger onboarding flows for new users who joined via invitation
• Apply referral bonuses or rewards to the inviter
• Update their UI to reflect the claimed status

Authentication

The webhook includes a signature in the X-UMAaas-Signature header that allows you to verify that the webhook was sent by UMAaas. To verify the signature:

1. Get the UMAaas public key provided to you during integration
2. Decode the base64 signature from the header
3. Create a SHA-256 hash of the request body
4. Verify the signature using the public key and the hash

If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.