Download Payout Proof of Payment (POP)

The Proof of Payment (POP) is the official confirmation document for a completed Payout transaction. Besides downloading it manually from the Business Portal, you can request it programmatically through the API.

Prerequisites

Before you begin, ensure you have:

• Valid API credentials with an active access token.
• One or more Payout transactions in Completed status.
• The internalId or externalId of each transaction you want a POP for.

API Endpoint

To download a Payout POP, send a POST request to the Download Payout Proof of Payment endpoint.

Endpoint

POST https://api.stage.localpayment.com/api/v1/payouts/proof-of-payment

Authentication

Include your access token in the request headers:

Authorization: Bearer <your_access_token>

Request Body

The body is a JSON array of transaction identifiers. You can mix internalId and externalId values in the same request.

Example Request

curl --request POST \
     --url https://api.stage.localpayment.com/api/v1/payouts/proof-of-payment \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '[
       "550e8400-e29b-41d4-a716-446655440000",
       "f47ac10b-58cc-4372-a567-0e02b2c3d479"
     ]'

Response Handling

Success Response

On success, the response body is the ZIP archive itself, base64-encoded as plain text. It is not wrapped in a JSON field: decode the response body directly to get the ZIP file, which contains one PDF Proof of Payment per requested transaction.

Error Responses

401 Unauthorized. The access token is missing, invalid, or expired.

{
  "code": "token_not_valid",
  "detail": "Given token not valid for any token type",
  "messages": [
    {
      "message": "Token is invalid or expired",
      "token_class": "AccessToken",
      "token_type": "access"
    }
  ]
}

403 Forbidden. One or more requested transactions are not in Completed status.

{
  "error": "INVALID_STATUS",
  "message": "Proof of Payment is only available for Completed transactions",
  "invalid_transactions": [
    {
      "transaction_id": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
      "current_status": "Cancelled"
    }
  ]
}

404 Not Found. None of the requested identifiers have Proof of Payment information available.

{
  "Status": 404,
  "Code": null,
  "Message": "There is no payments information to generate the file",
  "TraceId": "6a907fb4000000001f723f645b1fdee3"
}

Implementation Best Practices

• Validate that a transaction is Completed before requesting its POP.
• Batch multiple transaction IDs in a single request instead of calling the endpoint once per transaction.
• Store access tokens securely and rotate them regularly.