Send funds via Wallet

Wallet payouts allow you to send funds directly to the beneficiary's digital wallet. You can initiate these transfers through either:

Localpayment Dashboard: User-friendly interface for manual transaction management.
API Integration: Programmatic access for automated payout processing.

This guide focuses on API implementation, covering the complete flow from initialization to completion.

Before You Begin

Ensure you have:

Valid API credentials (access token).
Complete beneficiary information.
Proper account setup for your target country.
Understanding of country-specific requirements (see Country Requirements below).

Step 1: Initialize the Payout Transaction

To create a bank transfer payout, send a POST request to the Create a Payout endpoint with paymentMethod.type set Wallet.

Endpoint

POST https://api.stage.localpayment.com/api/payout/

Required Headers

Authorization: Bearer <your_access_token>

Key Request Parameters

The request requires several key objects:

Object	Description	Required
`beneficiary`	Recipient details including bank information	✅
`sender`	Sender information for compliance	✅
`merchant`	Merchant/business details	✅
`paymentMethod`	Payment method configuration	✅
`amount`	Transaction amount	✅
`currency`	Transaction currency code	✅
`country`	Target country code	✅

Example Request (Bolivia)

curl --request POST \
     --url https://api.stage.localpayment.com/api/payout/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "value": {
    "externalId": "07e80cf6-b11b-479c-ad9a-b952ec256cdb",
    "country": "BOL",
    "currency": "BOB",
    "amount": 1000,
    "paymentMethod": {
      "type": "Wallet",
      "code": "0021",
      "flow": "direct"
    },
    "beneficiary": {
      "name": "John",
      "lastName": "Doe",
      "type": "INDIVIDUAL",
      "document": {
        "type": "CI",
        "id": "7794986"
      },
      "bank": {
        "name": "Yape",
        "code": "990",
        "account": {
          "alias": "+59112345678"
        }
      }
    },
    "sender": {
      "type": "INDIVIDUAL",
      "name": "David",
      "lastName": "Doe",
      "document": {
        "type": "CI",
        "id": "4812012-1B"
      }
    },
    "merchant": {
      "type": "COMPANY",
      "name": "Company Name"
    },
    "accountNumber": "068.068.00000019",
    "conceptCode": "0039"
  }
}
'

Step 2: Handle the Response

Successful Response

A successful response includes detailed transaction information and tracking identifiers:

{
  "externalId": "07e80cf6-b11b-479c-ad9a-b952ec256cdb3",
  "internalId": "9cbdb959-acb0-49e5-a52a-a8f9dddcde15",
  "paymentMethod": {
    "code": "0021",
    "name": "BCP",
    "description": "Yape",
    "paymentMethodType": "Wallet"
  },
  "country": "BOL",
  "currency": "BOB",
  "amount": 1000,
  "accountNumber": "068.068.00000019",
  "clientCode": "0001",
  "clientName": "Acme",
  "status": {
    "code": "100",
    "description": "Received",
    "detail": "The payout was received"
  },
  "beneficiary": {
    "bank": {
      "name": "Yape",
      "code": "990",
      "countryISOCode3": null,
      "branch": null,
      "account": {
        "number": null,
        "type": null,
        "alias": "+59112345678",
        "pixKey": null,
        "phone": null
      }
    },
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "type": "CI",
      "id": "7794986"
    },
    "userReference": null,
    "email": null,
    "phone": null,
    "birthdate": "0001-01-01T00:00:00Z",
    "nationality": null,
    "address": null
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Company Name",
    "lastname": null,
    "document": null,
    "userReference": null,
    "email": null,
    "phone": null,
    "birthdate": "0001-01-01T00:00:00Z",
    "nationality": null,
    "address": null
  },
  "sender": {
    "type": "INDIVIDUAL",
    "name": "David",
    "lastname": "Doe",
    "document": {
      "type": "CI",
      "id": "4812012-1B"
    },
    "userReference": null,
    "email": null,
    "phone": null,
    "birthdate": "0001-01-01T00:00:00Z",
    "nationality": null,
    "address": null
  },
  "comment": null,
  "exchangeRateToken": null,
  "date": {
    "creationDate": "2025-10-10T22:03:25.5138845Z",
    "processedDate": "2025-10-10T22:03:25.5140817Z"
  },
  "errors": null,
  "internalLoteID": "151880"
}

Key Response Fields

Field	Description	Use Case
`internalId`	Localpayment's unique transaction identifier	Transaction tracking and support
`externalId`	Your reference number	Internal reconciliation
`status.code`	Current transaction status code	Status monitoring
`date.creationDate`	When transaction was created	Audit trail
`date.processedDate`	When transaction began processing	Processing time calculation

Error Response

When a request fails, you'll receive detailed error information:

[
  {
    "externalId": "1736488884",
    "internalId": "cd052d8c-8406-45f8-98aa-aff9876c3285",
    "status": {
      "code": "801",
      "description": "Rejected",
      "detail": "Params error"
    },
    "errors": [
      {
        "code": "300",
        "description": "Invalid param + [paymentMethod.code] + doesn´t exists for PAYMENT_METHOD_TYPE BankTransf"
      },
      {
        "code": "300",
        "description": "Invalid param + [beneficiary.document.id] + doesn´t match regex ^(20|23|24|25|26|27|30|33|34)-?\\d{2}[.]?\\d{3}[.]?\\d{3}-?\\d$"
      }
    ],
    "comment": "Addicional informetion"
  }
]

Step 3: Track Transaction Status

After submitting a payout, monitor its progress through these methods:

Webhooks (Recommended)

Receive real-time notifications when transaction status changes. Most efficient for production environments.

Status API Endpoint

Query transaction status programmatically. Useful for polling or recovering lost webhook notifications.

Dashboard View

Visual interface for monitoring transactions. Great for manual oversight and detailed transaction analysis.

Common Status Codes

Code	Status	Description
`100`	Received	The payout was received.
`101`	Locked	The payout has been confirmed and passed AML validations.
`102`	In Progress	The payout has been sent to the bank.
`104`	PendingAuth	The payout is pending of authorization by client.
`200`	Completed	The payout was debited.
`300`	Rejected	Invalid param + [param name] + [reason].

🗒️
Complete Reference
View all status codes in our Transaction Status Documentation.

Step 4: Transaction Approval

For enhanced security, certain transactions require two-person approval:

Initiator: Submits the payout request.
Approver: Reviews and confirms the transaction.

This process can be managed through the Dashboard or API endpoints.

🔒
Security Note
Approval requirements help prevent unauthorized transactions and ensure compliance with local regulations.

Country-Specific Requirements

Implementation details vary by country. Any country not explicitly mentioned adheres to the standard procedure without special requirements. Review these requirements before integration:

YAPE Payments:

paymentMethod.code: Set to 0021.
beneficiary.bank.code: Set to 990.
beneficiary.bank.account.alias: Must contain the beneficiary’s phone number in the format +591XXXXXXXX (full international format).
Omit the following fields: beneficiary.bank.account.type and beneficiary.bank.account.number.

Testing Your Integration

Sandbox Environment

Use the staging environment for testing:

https://api.stage.localpayment.com/api/payout/

Test Scenarios

Verify your integration handles these scenarios:

Successful Transaction: Standard payout flow
Validation Errors: Invalid bank account, missing fields
Processing Delays: Transactions that take time to process
Failed Transactions: Insufficient funds, blocked beneficiaries
Status Updates: Webhook handling and status polling

Resources & Next Steps

Maximize your integration success with these essential resources

Webhook Integration

Set up real-time notifications for transaction status updates.

Reporting Dashboard

Access detailed analytics, reporting tools, and reconciliation features.

Transaction Monitoring

Learn to query transaction status and implement comprehensive tracking.

API Reference

Complete endpoint documentation with interactive examples.

✅
Pro Tip
Always test your workflow in our sandbox environment before deploying to production. This ensures your error handling, webhook processing, and status tracking work correctly across all scenarios.

🎧
Need Help?
Contact our support team if you experience any issues or need assistance for integration.