Skip to content
API Reference
/
/Payout

Almond Payout API (1.1.0)

The Almond Payout API enables clients to execute domestic payouts by leveraging local banking partners and payout networks.

As a client, you need to:

  • Authenticate to obtain an access token.
  • Discover payout providers by querying supported providers by country and retrieving provider-specific field requirements.
  • Check payout rates and fees for full transparency on send/receive amounts.
  • Create a payout with the required beneficiary and payment details.

Almond then orchestrates the process — verifying balance availability, executing the payout through the chosen payout partner, and updating the payout status — while providing clients with real-time status updates and notifications.

System Flow
Figure: Payout Flow

Download OpenAPI description
payouts.json
payouts.yaml
Overview
URL
https://www.almondfintech.com/contact-us
Almond Fintech API Support
info@almondfintech.com
License
Copyright © 2025 Almond FinTech. All rights reserved.
Languages
Servers
Mock server
https://docs.almondfintech.com/_mock/apis/payouts
Sandbox
https://api.sandbox.almondfintech.com
Production
https://api.almondfintech.com

Member

Operations

Payout Providers

Operations

Static Fields

Operations

Payout

Operations

Get Payout Limits

Request

Retrieves the minimum and maximum payout limits for payout providers based on the specified country code and/or payout provider ID.

Query Parameters:

  • At least one of countryCode or payoutProviderId must be provided.

Response:

  • Returns a list of payout limits, each containing the currency code, minimum limit, and maximum limit.

Use Cases:

  • Check payout limits before initiating a payout
  • Display available payout limits to end users
  • Validate payout amounts against configured limits
Query
countryCodestring^[A-Za-z]{2}$

Country Code

payoutProviderIdstring^[A-Za-z_]*$
curl -i -X GET \
  'https://docs.almondfintech.com/_mock/apis/payouts/v2/payout-limits?countryCode=string&payoutProviderId=string'

Responses

List of payout limits response

Bodyapplication/jsonArray [
currencystring^[A-Z]{3}$
minimumLimitnumber
maximumLimitnumber
]
Response
application/json
[
  {
    "currency": "PHP",
    "minimumLimit": 500,
    "maximumLimit": 250000
  }
]

Initiate Payout

Request

Creates a new payout with the provided request details.

  • On success, the response includes:
    • payoutId – Unique identifier for the initiated payout. This ID must be used for subsequent operations (e.g., status checks, cancellation).
    • payoutStatus – Will return "ACCP" if the payout request is received successfully.

This endpoint is the entry point for executing a payment or transfer, and serves as the foundation for all subsequent payout lifecycle operations.

Bodyapplication/jsonrequired
senderobject(Sender)required
sender.​firstNamestringnon-emptyrequired
sender.​middleNamestring
sender.​lastNamestringrequired
sender.​lastName2string
sender.​genderstring(GenderEnum)
Enum"M""F"
sender.​dateOfBirthstring(date)
sender.​countryOfBirthstring^[A-Z]{3}$
sender.​idNumberstring
sender.​idTypestring
sender.​passportNumberstring
sender.​accountNumberstring
sender.​nationalitystring^[A-Za-z ]{2,60}$
sender.​occupationstring
sender.​phonestring
sender.​emailstring(email)
Example: "abc@example.com"
sender.​addressobject(AddressInfo)
sender.​countryCodestring^[A-Z]{2}$
sender.​companyNamestring
sender.​companyTradingNamestring
sender.​companyRegistrationNumberstring
sender.​companyRegistrationCountrystring
beneficiaryobject(Beneficiary)required
beneficiary.​firstNamestringnon-emptyrequired
beneficiary.​middleNamestringnon-empty
beneficiary.​lastNamestringrequired
beneficiary.​lastName2string
beneficiary.​genderstring(GenderEnum)
Enum"M""F"
beneficiary.​dateOfBirthstring(date)
beneficiary.​countryOfBirthstring
beneficiary.​stateOfBirthstring
beneficiary.​phonestring
beneficiary.​mailAddressstring
beneficiary.​countryCodestring^[A-Z]{2}$
beneficiary.​emailstring(email)
Example: "abc@example.com"
beneficiary.​addressobject(AddressInfo)
beneficiary.​accountNamestring
beneficiary.​accountNumberstring
beneficiary.​accountTypestring
beneficiary.​transferNumberstring
beneficiary.​idNumberstring
beneficiary.​idTypestring
beneficiary.​idIssueStatestring
beneficiary.​idIssueCountrystring
beneficiary.​pixTypestring
beneficiary.​pixKeystring[ 1 .. 100 ] characters
beneficiary.​taxIdstring[ 1 .. 100 ] characters
beneficiary.​idExpiryDatestring(date)
beneficiary.​idIssueDatestring(date)
beneficiary.​passportNumberstring
beneficiary.​nationalitystring^[A-Za-z ]{2,60}$
beneficiary.​typestring
beneficiary.​residencyTypestring
beneficiary.​occupationstring
beneficiary.​companyNamestring
beneficiary.​branchNumberstringnon-empty
complianceInfoobject(ComplianceInfo)
sourceMemberPayoutIdstring[ 1 .. 50 ] charactersrequired
destinationCcystring^[A-Z]{3}$required
payoutAmtnumberrequired
payoutProviderIdstring^[A-Za-z0-9-_ ]*$required
payoutMethodstring(PayoutMethodEnum)

BANK_ACCOUNT: Bank Account service,

CASH_PICKUP: Cash pickup service,

WALLET: Wallet service

Enum"BANK_ACCOUNT""CASH_PICKUP""WALLET"
segmentstring(SegmentEnum)

C2C: From an individual to an individual,

B2B: From a business to a business

Enum"C2C""B2B"
curl -i -X POST \
  https://docs.almondfintech.com/_mock/apis/payouts/v2/payouts \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceMemberPayoutId": "PAYOUT-2024-003",
    "payoutProviderId": "PAYOUT-PROVIDER-1",
    "destinationCcy": "PHP",
    "payoutAmt": 5500,
    "payoutMethod": "BANK_ACCOUNT",
    "segment": "C2C",
    "sender": {
      "firstName": "Jane",
      "lastName": "Smith",
      "countryCode": "US"
    },
    "beneficiary": {
      "firstName": "John",
      "lastName": "Doe",
      "accountNumber": "1234567890",
      "countryCode": "PH"
    },
    "complianceInfo": {
      "purpose": "FAMILY_MAINTENANCE"
    }
  }'

Responses

Payout Initiated.

Headers
Locationstring

Location of the created resource i.e. GET /v2/payouts/{payout-id}

Bodyapplication/json
payoutIdstring

Resource identification of the related payout initiation in UUID v04 format.

sourceMemberPayoutIdstring
payoutStatusstring(PayoutStatusEnum)

RCVD: Received,

ACCP: Accepted,

PNDG: Pending,

PRCD: Processed,

RJCT: Rejected,

CNCL: Cancelled,

EXPD: Expired,

FAIL: Failed,

RVSD: Reversed

Enum"RCVD""ACCP""PNDG""PRCD""RJCT""CNCL""EXPD""FAIL""RVSD"
destinationCcystring
payoutAmtnumber
transferFeenumber
expiryTimestring(date-time)
beneficiaryNamestring
linksobject(Links)
Response
application/json
{
  "payoutId": "a4685b57-8788-4b4b-a35f-1066b68c23ea",
  "sourceMemberPayoutId": "PAYOUT-2024-001",
  "payoutStatus": "ACCP",
  "destinationCcy": "PHP",
  "payoutAmt": 5500,
  "transferFee": 5,
  "beneficiaryName": "John Doe",
  "expiryTime": "2026-01-21T08:07:13.597048Z",
  "links": {
    "process": "/v2/payouts/a4685b57-8788-4b4b-a35f-1066b68c23ea/process\"",
    "status": "/v2/payouts/a4685b57-8788-4b4b-a35f-1066b68c23ea/status",
    "details": "/v2/payouts/a4685b57-8788-4b4b-a35f-1066b68c23ea"
  }
}

Get Payouts

Request

Get payouts with filter and pagination support.

Example Request:

GET /v2/payouts?page=0&size=10&payoutStatus=ACCP&senderCountry=US&beneficiaryCountry=PH

Query Parameters:

  • page - Page number (default: 0)
  • size - Number of records per page (default: 10)
  • sortField - Field to sort by
  • sortDirection - Sort direction (ASC/DESC)
  • sourceMemberPayoutId - Filter by source member payout ID (your unique payout identifier)
  • payoutId - Filter by system payout ID (UUID format)
  • creationTime - Filter by creation date (YYYY-MM-DD)
  • completionTime - Filter by completion date (YYYY-MM-DD)
  • senderName - Filter by sender name
  • senderCountry - Filter by sender country code
  • beneficiaryName - Filter by beneficiary name
  • beneficiaryCountry - Filter by beneficiary country code
  • payoutProviderId - Filter by payout provider id
  • payoutStatus - Filter by payout status (ACCP, PNDG, PRCD, etc.)
Query
pageinteger

page number

Default 0
sizeinteger

page size. default is 10

Default 10
sortFieldstring(PayoutSortEnum)

Payout sort field

Enum"sourceMemberPayoutId""payoutId""creationTime""completionTime""senderName""senderCountry""beneficiaryName""beneficiaryCountry""payoutProviderId""payoutStatus"
sortDirectionstring(SortDirectionEnum)

sort direction

Enum"asc""desc"
sourceMemberPayoutIdstring

Filter by source member payout ID (your unique payout identifier)

payoutIdstring

Filter by system payout ID (UUID format)

creationTimestring(date)
completionTimestring(date)
senderNamestring
senderCountrystring
beneficiaryNamestring
beneficiaryCountryinteger
payoutProviderIdstring
payoutStatusstring
curl -i -X GET \
  'https://docs.almondfintech.com/_mock/apis/payouts/v2/payouts?page=0&size=10&sortField=sourceMemberPayoutId&sortDirection=asc&sourceMemberPayoutId=string&payoutId=string&creationTime=2019-08-24&completionTime=2019-08-24&senderName=string&senderCountry=string&beneficiaryName=string&beneficiaryCountry=0&payoutProviderId=string&payoutStatus=string'

Responses

Payout List Response

Bodyapplication/json
payoutsArray of objects(PayoutResponse)
pageinteger
sizeinteger
totalPagesinteger
totalRecordsinteger(int64)
Response
application/json
{
  "payouts": [
    { … },
    { … }
  ],
  "totalPages": 5,
  "totalRecords": 42,
  "page": 0,
  "size": 10
}

Process Payout

Request

Path
payout-idstringrequired

Identification of payout created (resource identification of the generated payout initiation resource).

curl -i -X POST \
  'https://docs.almondfintech.com/_mock/apis/payouts/v2/payouts/{payout-id}/process'

Responses

Payout Processed.

Bodyapplication/json
payoutStatusstring(PayoutStatusEnum)

RCVD: Received,

ACCP: Accepted,

PNDG: Pending,

PRCD: Processed,

RJCT: Rejected,

CNCL: Cancelled,

EXPD: Expired,

FAIL: Failed,

RVSD: Reversed

Enum"RCVD""ACCP""PNDG""PRCD""RJCT""CNCL""EXPD""FAIL""RVSD"
cashoutStatusstring
rejectReasonstring
Response
application/json
{
  "payoutStatus": "PRCD",
  "cashoutStatus": "Y"
}

Get Payout Details

Request

Fetches detailed information about a specific payout using its unique payoutId.

Returns comprehensive payout information including:

  • Payout details (amount, transfer fee)
  • Sender and beneficiary information
  • Current payout status
  • Timestamps (creation, completion)
  • Compliance information
Path
payout-idstringrequired

Identification of payout created (resource identification of the generated payout initiation resource).

curl -i -X GET \
  'https://docs.almondfintech.com/_mock/apis/payouts/v2/payouts/{payout-id}'

Responses

Payout response

Bodyapplication/json
payoutIdstring

Resource identification of the related payout initiation in UUID v04 format.

sourceMemberPayoutIdstring
payoutStatusstring(PayoutStatusEnum)

RCVD: Received,

ACCP: Accepted,

PNDG: Pending,

PRCD: Processed,

RJCT: Rejected,

CNCL: Cancelled,

EXPD: Expired,

FAIL: Failed,

RVSD: Reversed

Enum"RCVD""ACCP""PNDG""PRCD""RJCT""CNCL""EXPD""FAIL""RVSD"
cashoutStatusstring
rejectReasonstring
destinationCcystring
payoutAmtnumber
transferFeenumber
expiryTimestring(date-time)
payoutProviderIdstring
segmentstring(SegmentEnum)

C2C: From an individual to an individual,

B2B: From a business to a business

Enum"C2C""B2B"
payoutMethodstring(PayoutMethodEnum)

BANK_ACCOUNT: Bank Account service,

CASH_PICKUP: Cash pickup service,

WALLET: Wallet service

Enum"BANK_ACCOUNT""CASH_PICKUP""WALLET"
senderobject(Sender)
beneficiaryobject(Beneficiary)
complianceInfoobject(ComplianceInfo)
creationTimestring(date-time)
initiateTimestring(date-time)
completionTimestring(date-time)
rejectionTimestring(date-time)
cancellationTimestring(date-time)
Response
application/json
{
  "payoutId": "a4685b57-8788-4b4b-a35f-1066b68c23ea",
  "payoutStatus": "ACCP",
  "sourceMemberPayoutId": "PAYOUT-2024-001",
  "sender": {
    "firstName": "Jane",
    "middleName": "Marie",
    "lastName": "Smith",
    "countryCode": "US",
    "phone": "+1-555-0123",
    "email": "jane.smith@example.com",
    "entityType": "INDIVIDUAL"
  },
  "beneficiary": {
    "firstName": "John",
    "middleName": "Carlos",
    "lastName": "Doe",
    "countryCode": "PH",
    "accountNumber": "1234567890",
    "accountName": "John C. Doe",
    "phone": "+63-917-1234567",
    "entityType": "INDIVIDUAL"
  },
  "payoutAmt": 5500,
  "destinationCcy": "PHP",
  "transferFee": 5,
  "expiryTime": "2024-12-18T12:00:00Z",
  "payoutProviderId": "PAYOUT-PROVIDER-1",
  "payoutMethod": "BANK_ACCOUNT",
  "segment": "C2C",
  "compliance": {
    "sourceOfFunds": "SALARY",
    "purpose": "FAMILY_MAINTENANCE",
    "relationship": "PARENT"
  },
  "creationTime": "2026-01-21T08:07:10Z",
  "intiateTime": "2026-01-21T08:07:13Z"
}

Get Payout Status

Request

Retrieves the current status of a specific payout using its unique payoutId.

Payout Status Values:

  • RCVD - Received: Payout request has been received
  • ACCP - Accepted: Payout has been accepted for processing
  • PNDG - Pending: Payout is pending processing
  • PRCD - Processed: Payout has been successfully processed
  • RJCT - Rejected: Payout was rejected
  • CNCL - Cancelled: Payout was cancelled
  • EXPD - Expired: Payout has expired
  • FAIL - Failed: Payout processing failed
  • RVSD - Reversed: Payout was reversed

Cancellation Status Values (when applicable):

  • ACCP - Cancellation accepted
  • PNDG - Cancellation pending
  • PRCD - Cancellation processed
  • RJCT - Cancellation rejected
Path
payout-idstringrequired

Identification of payout created (resource identification of the generated payout initiation resource).

curl -i -X GET \
  'https://docs.almondfintech.com/_mock/apis/payouts/v2/payouts/{payout-id}/status'

Responses

Payout status response

Bodyapplication/json
payoutStatusstring(PayoutStatusEnum)

RCVD: Received,

ACCP: Accepted,

PNDG: Pending,

PRCD: Processed,

RJCT: Rejected,

CNCL: Cancelled,

EXPD: Expired,

FAIL: Failed,

RVSD: Reversed

Enum"RCVD""ACCP""PNDG""PRCD""RJCT""CNCL""EXPD""FAIL""RVSD"
payoutCancellationStatusstring(PayoutCancellationStatusEnum)

ACCP: Accepted,

PNDG: Pending,

PRCD: Processed,

RJCT: Rejected

Enum"ACCP""PNDG""PRCD""RJCT"
cashoutStatusstring
rejectReasonstring
Response
application/json
{
  "payoutStatus": "ACCP"
}

Cancel Payout

Request

Submits a cancellation request for a specific payout identified by its unique payoutId.

Path
payout-idstringrequired

Identification of payout created (resource identification of the generated payout initiation resource).

Bodyapplication/jsonrequired
cancellationReasonstring[ 1 .. 50 ] charactersrequired
curl -i -X POST \
  'https://docs.almondfintech.com/_mock/apis/payouts/v2/payouts/{payout-id}/cancel' \
  -H 'Content-Type: application/json' \
  -d '{
    "cancellationReason": "Customer requested cancellation"
  }'

Responses

Payout cancellation initiated.

Bodyapplication/json
payoutStatusstring(PayoutStatusEnum)

RCVD: Received,

ACCP: Accepted,

PNDG: Pending,

PRCD: Processed,

RJCT: Rejected,

CNCL: Cancelled,

EXPD: Expired,

FAIL: Failed,

RVSD: Reversed

Enum"RCVD""ACCP""PNDG""PRCD""RJCT""CNCL""EXPD""FAIL""RVSD"
payoutCancellationStatusstring(PayoutCancellationStatusEnum)

ACCP: Accepted,

PNDG: Pending,

PRCD: Processed,

RJCT: Rejected

Enum"ACCP""PNDG""PRCD""RJCT"
Response
application/json
{
  "payoutStatus": "ACCP",
  "payoutCancellationStatus": "PNDG"
}
Copyright © 2025 Almond FinTech. All rights reserved.