{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"fb7d9328-d944-41b5-8605-d459ea859701","name":"Liberpay API Docs","description":"# Getting Started\n\nLiberpay is a self-custody payment platform. Buyers pay in crypto (for example, USDC on Polygon) or in fiat (card, Pix). The money goes to the seller's wallet or account. Liberpay does not hold it.\n\nTo use the API, you need a Liberpay account. Go to [https://liberpay.com](https://liberpay.com) to create one.\n\n# Base URL\n\nAll API calls use this base URL:\n\n`https://api.liberpay.com`\n\nIn this collection, the `{{baseURL}}` variable holds the base URL. Every path starts with `/api`.\n\n# Authentication\n\n## Create an API key\n\n1. Sign in at [https://app.liberpay.com](https://app.liberpay.com).\n2. Open your profile page.\n3. In the **API Keys** section, create a new key.\n4. Copy the key and keep it in a safe place. Liberpay shows the key only one time.\n\nAn API key does not expire. It stays valid until you revoke it. You can also manage keys with the endpoints in the **auth** folder.\n\n## Send the key\n\nSend the key in the `Authorization` header of each request:\n\n```\nAuthorization: Bearer <your API key>\n```\n\nIn this collection, put your key in the `{{token}}` variable. The collection sends it on every request.\n\nAn API key acts as the user who created it. It can do all the things that the user can do. Keep your keys secret. Do not put them in browser or mobile app code.\n\nSome endpoints are public and do not need a key. The description of each endpoint tells you if it needs a key.\n\n# Requests and Responses\n\n- Send request bodies as JSON, with the header `Content-Type: application/json`. File uploads use `multipart/form-data`.\n- Most successful responses put the result in a `data` key: `{\"data\": {...}}` or `{\"data\": [...]}`.\n- Amounts in fiat are decimal strings, for example `\"102.00\"`. Amounts in crypto are integer strings in the smallest unit of the token (for example, USDC has 6 decimals, so `\"1000000\"` is 1 USDC).\n- Timestamps use ISO 8601 in UTC. Some fields do not include the `Z` suffix.\n\n## Optional headers and parameters\n\n| Name | Where | Use |\n|---|---|---|\n| `X-Liberpay-Locale` | header | The language of messages in the response. Values: `en-US`, `pt-BR`. Without it, Liberpay uses the user's language. |\n| `X-Liberpay-Country` | header | A country code (`BR`, `US`) for anonymous calls. It sets default language and currency. It never changes the country of a signed-in user. |\n| `viewer_currency` | query | A fiat currency symbol, for example `USD`. Responses that show charges then also convert prices to this currency. |\n\n# Errors\n\nLiberpay uses standard HTTP status codes. Error bodies use these shapes:\n\n| Status | When | Body |\n|---|---|---|\n| 400 | A parameter is missing or not valid. | `{\"status\": \"error\", \"message\": \"...\"}` |\n| 401 | The token is missing or not valid. | `{\"status\": \"error\", \"message\": \"Unauthorized!\"}` |\n| 403 | The token is valid, but the user cannot do this action. | `{\"status\": \"error\", \"message\": \"...\"}` |\n| 404 | The resource does not exist, or you cannot see it. | `{\"status\": \"error\", \"message\": \"...\"}` or `{\"errors\": {\"detail\": \"Not Found\"}}` |\n| 409 | The account must complete a step first. For example, a user with no country can only read. | `{\"status\": \"error\", \"code\": \"country_required\", \"message\": \"...\"}` |\n| 422 | The data is not valid. `errors` lists the fields. | `{\"status\": \"error\", \"errors\": {\"field\": [\"message\"]}}` |\n| 429 | Too many requests. Some public endpoints have a rate limit. | `{\"status\": \"error\", \"message\": \"...\"}` |\n\nThe `message` text uses the language of the request.\n\nSome business rules return 500 with a `message` today, for example \"charge must have created status\". Read the `message` text, not only the status code.\n\n# The Charge Lifecycle\n\nTo accept a payment, you, the seller, first create a **charge** with the **charges › create** endpoint.\n\nA charge has one of 10 statuses:\n\n| Id | Status | Meaning |\n|---|---|---|\n| 1 | `created` | The default for a new charge. The charge waits for payment. |\n| 2 | `pending` | A payment was reported. Liberpay has not confirmed it yet. |\n| 3 | `confirmed` | Liberpay verified the payment. |\n| 4 | `expired` | The price quote expired before payment. |\n| 5 | `failed` | A payment was reported, but it failed. |\n| 6 | `underpaid` | A payment was reported, but it was less than the price. |\n| 7 | `refund_pending` | A refund is in progress. |\n| 8 | `refunded` | The refund was sent and verified. |\n| 9 | `refund_failed` | The refund failed or was not valid. |\n| 10 | `canceled` | The charge was canceled. |\n\nImportant rules:\n\n- **Payment link.** Every charge has a payment link: `https://app.liberpay.com/charges/:shortcode/pay`. While a charge is `created`, anyone with the shortcode can read it. After that, only the parties of the charge can read it.\n- **Price quote.** When you create a charge, update it, or set its payment currency, Liberpay gets a new price quote and calculates the crypto amount again. The quote has an expiry time (`expires_at`). After expiry, set the currency again or update the charge to get a new quote.\n- **Fiat payments** (card, Pix) update the charge status automatically through the payment provider.\n- **Crypto payments** must be reported after the buyer pays. Use **charges › reportTransaction**. Liberpay then verifies the transaction on the blockchain.\n\n# Accept a Payment\n\n## Hosted payment page (recommended)\n\nThis is the easiest integration:\n\n1. Create the charge with the API.\n2. Send the buyer to the payment link.\n\nLiberpay hosts the payment page. It handles currency selection, the charge nonce and hash, wallet connection, fiat checkout, and the report of blockchain transactions.\n\n## Your own payment page\n\nYou can build your own payment page. This takes more work. At a high level, you must:\n\n1. Get the gateways of the charge's store.\n2. Get the currencies that those gateways accept.\n3. Set the charge currency each time the buyer selects a currency.\n4. For ERC-20 tokens, ask the buyer to approve the token, then send the payment.\n5. For fiat, create a fiat link (see the **fiat links** folder) and send the buyer to it.\n6. Get the charge nonce and hash from the `generateCommitment` method of the `NFTiPayReceipt` contract.\n7. Report the transaction after the buyer pays.\n\nWe can help you with your integration. Write to [support@liberpay.com](mailto:support@liberpay.com).\n\n# Webhooks\n\nLiberpay does not send webhooks to your server yet. To know when a charge changes status, read the charge with **charges › get** at regular intervals. Stop when the status is final (for example `confirmed`, `expired`, `failed` or `canceled`).\n\nThe **events** folder is not a webhook system. It records activity on an invoice, for example when a buyer views it.\n\n# Smart Contracts and Addresses\n\nNFT receipts from Liberpay come only from this contract:\n\n**Polygon Mainnet (NFTiPayReceipt):** `0x714256086AC8636E95FE28D1b010a0083A684c6d`\n\nGateway fees and other platform fees on the blockchain are paid only in official USDC to this address:\n\n**Main fee wallet:** `0xB00a8eb1e0774401208F9507d0d69360F42B9B97`\n\n# Support\n\nWrite to [support@liberpay.com](mailto:support@liberpay.com) for help.\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"47943201","team":9759437,"collectionId":"fb7d9328-d944-41b5-8605-d459ea859701","publishedId":"2sBYHVvJcU","public":true,"publicUrl":"https://us.docs.liberpay.com","privateUrl":"https://go.postman.co/documentation/47943201-fb7d9328-d944-41b5-8605-d459ea859701","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"20a5f3"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":"LiberPay API Docs - US English"}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"20a5f3"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"20a5f3"}}]}},"version":"8.12.10","publishDate":"2026-10-27T16:39:37.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"LiberPay API Docs - US English","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/9acc00e63ea4d80eb3a446a0547b8fa13c680b0fc212a0289a6a475620602f41","favicon":"https://liberpay.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://us.docs.liberpay.com/view/metadata/2sBYHVvJcU"}