Guides
GuidesAPI ReferenceGo to DashboardSite >
Start typing to search…

Send funds via Wallet

Send funds via wallet using Localpayment’s API. Learn how to create payouts, manage responses, and meet country requirements.

Send funds via Wallet using Localpayment's API. This guide covers everything you need to know about creating payouts, handling responses, managing transaction status, and meeting country-specific requirements.

Overview

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:

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:

ObjectDescriptionRequired
beneficiaryRecipient details including bank information✅
senderSender information for compliance✅
merchantMerchant/business details✅
paymentMethodPayment method configuration✅
amountTransaction amount✅
currencyTransaction currency code✅
countryTarget 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

FieldDescriptionUse Case
internalIdLocalpayment's unique transaction identifierTransaction tracking and support
externalIdYour reference numberInternal reconciliation
status.codeCurrent transaction status codeStatus monitoring
date.creationDateWhen transaction was createdAudit trail
date.processedDateWhen transaction began processingProcessing 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

CodeStatusDescription
100ReceivedThe payout was received.
101LockedThe payout has been confirmed and passed AML validations.
102In ProgressThe payout has been sent to the bank.
104PendingAuthThe payout is pending of authorization by client.
200CompletedThe payout was debited.
300RejectedInvalid param + [param name] + [reason].
📝

Note: For complete status code reference, see the Transaction Status Documentation.

Step 4: Transaction Approval

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

  1. Initiator: Submits the payout request.
  2. 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:

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

Next Steps

Webhook Integration

Set up real-time notifications for transaction status changes

Reporting & Analytics

Access detailed transaction reports and reconciliation tools

Error Code Reference

Complete guide to error codes and troubleshooting

API Reference

Detailed API endpoint documentation and parameter reference

Support & Resources

Need help with your integration?

  • Technical Support: Contact our support team for integration assistance
  • Documentation: Visit our complete API reference
💡

Pro Tip: Start with small test transactions in our sandbox environment to verify your integration before processing live payments.


Updated 5 days ago