# NFT invoice payment method integration guide The integration flow is: 1. Create an API key 2. Configure an invoice webhook URL 3. Create an NFT Pay invoice 4. Forward your end user to a hosted payment page by opening it in a separate browser tab. Using hosted payment pages within iframes is not allowed 5. Receive invoice status updates by webhook 6. Mark the payment as successful once the invoice reaches completed To create the invoice request itself, use the standard Create Invoice API described here: {% content-ref url="creating-invoice" %} [creating-invoice](https://docs.txn.io/invoices/creating-invoice) {% endcontent-ref %} ## Before you begin Make sure you have: * access to your txn merchant back office * an API key for the environment you are using * a public webhook endpoint that can receive POST requests You should use: * Sandbox for testing * Production for live payments ### Sandbox Sandbox replicates the production environment by routing requests to the sandbox module for test purchases and smart contract interactions. It is connected to testnet blockchains, so no real charges are made and no real funds are used. OTP codes are also not sent to your phone in Sandbox - the code is always 0000. ### Test cards details Cards are not charged in the Sandbox environment. However, please do not use real card details there. You may use any card number and expiry date, or generate test card details on [this site](https://www.testmuai.com/free-online-tools/credit-card-number-generator/). To simulate a successful card purchase you can use CVV `000`. ### Required parameter summary | **Environment** | **chargedCurrency** | **network** | **paymentMethods** | | --------------- | ------------------- | ---------------- | ------------------ | | Sandbox | `POL` | `tpolygon` | `["nft"]` | | Production | `USDC` | `polygon:usdcv2` | `["nft"]` | *** ## 1. Create an API key In the txn back office, go to **Developers** → **API Keys** and create a new API key for your integration. This API key will be used to authenticate requests to the txn API. Include it in every request as a Bearer token: ```html Authorization: Bearer Content-Type: application/vnd.api+json ``` Use your sandbox key in sandbox and your production key in production. ## 2. Configure your webhook URL To receive invoice status updates, configure a webhook endpoint in the txn back office. Go to **Developers** → **Webhook URLs** and click **Add Webhook URL**. When creating the webhook: * enter a webhook label * enter your webhook endpoint URL * enable **API Invoices** * optionally associate the webhook with specific API keys if required Once saved, txn will send invoice webhook events to that endpoint. ### Webhook endpoint requirements Your webhook endpoint should: * accept POST requests * read the **raw request body** * verify the webhook signature before processing * return a 2xx response quickly after the event is accepted Your processing should also be **idempotent**, so duplicate webhook deliveries do not result in duplicate order fulfilment. ## 3. Create an NFT Pay invoice To create an NFT Pay invoice, use the standard **Create Invoice** endpoint: ```html POST /api/public/v1/invoices ``` For this payment method, the following attributes must always be set exactly as shown below. ### Required NFT parameters #### Production {% code lineNumbers="true" %} ```json { "chargedCurrency": "USDC", "network": "polygon:usdcv2", "paymentMethods": ["nft"] } ``` {% endcode %} #### Sandbox {% code lineNumbers="true" %} ```json { "chargedCurrency": "POL", "network": "tpolygon", "paymentMethods": ["nft"] } ``` {% endcode %} These values are required for NFT and should not be changed. ## 4. Example requests #### Production example {% code lineNumbers="true" %} ```bash curl -X POST "https://api.txn.io/api/public/v1/invoices" \ -H "Authorization: Bearer " \ -H "Content-Type: application/vnd.api+json" \ -d '{ "data": { "type": "invoices", "attributes": { "amountBilled": "100.00", "billedCurrency": "USD", "chargedCurrency": "USDC", "network": "polygon:usdcv2", "paymentMethods": ["nft"], "reference": "order_12345" } } }' ``` {% endcode %} #### Sandbox example {% code lineNumbers="true" %} ```bash curl -X POST "https://api.sandbox.txn.io/api/public/v1/invoices" \ -H "Authorization: Bearer " \ -H "Content-Type: application/vnd.api+json" \ -d '{ "data": { "type": "invoices", "attributes": { "amountBilled": "100.00", "billedCurrency": "USD", "chargedCurrency": "POL", "network": "tpolygon", "paymentMethods": ["nft"], "reference": "order_12345" } } }' ``` {% endcode %} ## 5. Store the invoice identifiers When the invoice is created successfully, txn returns an invoice object in the response. You should store at least: * the txn invoice ID * your internal `reference` * any internal order or customer identifiers linked to the payment The `reference` field is important because it allows you to map later webhook events back to the correct order in your system. ## **6. Handle invoice webhook events** After the invoice is created, txn will send webhook events to your configured webhook URL as the invoice status changes. For this integration, you should treat the payment as successful when the invoice status becomes: ```json "completed" ``` Once you receive a valid webhook showing status = "completed", you should: * mark the order as paid * fulfil the NFT purchase or unlock the related service * store the payment result in your system Do not fulfil the order before the invoice reaches completed. ## 7. Example webhook handling logic The example below shows the expected webhook processing flow. ```javascript app.post("/webhooks/txn", express.raw({ type: "*/*" }), async (req, res) => { const rawBody = req.body.toString("utf8"); const svixId = req.header("svix-id"); const svixTimestamp = req.header("svix-timestamp"); const svixSignature = req.header("svix-signature"); // Verify the webhook signature using the raw body and headers // Parse the payload only after verification succeeds const event = JSON.parse(rawBody); const invoice = event.data; const invoiceId = invoice.id; const status = invoice.attributes?.status; const reference = invoice.attributes?.reference; if (status === "completed") { // Mark the internal order as paid // Fulfil the NFT purchase // Store the invoice as processed } res.status(200).send("ok"); }); ``` ## 8. Recommended processing rules For a reliable integration, we recommend the following: #### Verify webhook authenticity Always verify the webhook signature before trusting the payload. Webhook deliveries may be retried. Your system should be able to safely receive the same event more than once without fulfilling the same order twice. #### Reconcile by reference Use your `reference` field, together with the txn invoice ID, to match incoming webhook events to the correct internal order. #### Fulfil only on completed Only treat the payment as successful once the invoice status is `completed`. ## 9. End-to-end flow summary A typical NFT Pay integration flow looks like this: 1. Create an API key in **Developers** → **API Keys** 2. Configure a webhook in **Developers** → **Webhook URLs** with **API Invoices** enabled 3. Create an invoice using the standard Create Invoice API 4. Set the required NFT Pay parameters for the target environment 5. Store the invoice ID and your internal reference 6. Receive webhook notifications for invoice status changes 7. Once the invoice reaches `completed`, mark the payment as successful and fulfil the order *** ## FAQ ### Supported countries | Country | Supported | | -------------------------------------------- | --------- | | Afghanistan | ✗ | | Aland Islands | ✓ | | Albania | ✓ | | Algeria | ✓ | | American Samoa | ✓ | | Andorra | ✓ | | Angola | ✓ | | Anguilla | ✓ | | Antigua and Barbuda | ✓ | | Argentina | ✓ | | Armenia | ✓ | | Aruba | ✓ | | Australia | ✓ | | Austria | ✓ | | Azerbaijan | ✓ | | Bahamas | ✓ | | Bahrain | ✓ | | Bangladesh | ✓ | | Barbados | ✓ | | Belarus | ✗ | | Belgium | ✓ | | Belize | ✓ | | Benin | ✓ | | Bermuda | ✓ | | Bhutan | ✓ | | Bolivia | ✓ | | Bonaire, Sint Eustatius and Saba | ✓ | | Bosnia and Herzegovina | ✓ | | Botswana | ✓ | | Bouvet Island | ✗ | | Brazil | ✓ | | British Indian Ocean Territory | ✓ | | British Virgin Islands | ✓ | | Brunei Darussalam | ✓ | | Bulgaria | ✓ | | Burkina Faso | ✓ | | Burundi | ✓ | | Cambodia | ✓ | | Cameroon | ✓ | | Canada | ✓ | | Cape Verde (Cabo Verde) | ✓ | | Cayman Islands | ✗ | | Central African Republic | ✓ | | Chad | ✓ | | Chile | ✓ | | China | ✓ | | Christmas Island | ✓ | | Cocos (Keeling) Islands | ✓ | | Colombia | ✓ | | Comoros | ✓ | | Cook Islands | ✓ | | Costa Rica | ✓ | | Cote D'Ivoire | ✓ | | Croatia | ✓ | | Cuba | ✗ | | Curaçao | ✓ | | Cyprus | ✓ | | Czech Republic | ✓ | | Democratic Republic of the Congo | ✗ | | Denmark | ✓ | | Djibouti | ✓ | | Dominica | ✓ | | Dominican Republic | ✓ | | Ecuador | ✓ | | Egypt | ✗ | | El Salvador | ✓ | | Equatorial Guinea | ✓ | | Eritrea | ✓ | | Estonia | ✓ | | Eswatini (Swaziland) | ✓ | | Ethiopia | ✓ | | Falkland Islands (Malvinas) | ✓ | | Faroe Islands | ✓ | | Fiji | ✓ | | Finland | ✓ | | France | ✓ | | French Guiana | ✓ | | French Polynesia | ✓ | | French Southern Territories | ✗ | | Gabon | ✓ | | Gambia | ✓ | | Georgia | ✓ | | Germany | ✓ | | Ghana | ✓ | | Gibraltar | ✗ | | Greece | ✓ | | Greenland | ✓ | | Grenada | ✓ | | Guadeloupe | ✓ | | Guam | ✓ | | Guatemala | ✓ | | Guernsey | ✓ | | Guinea | ✓ | | Guinea-Bissau | ✓ | | Guyana | ✓ | | Haiti | ✓ | | Heard Island and McDonald Islands | ✗ | | Honduras | ✓ | | Hong Kong | ✓ | | Hungary | ✓ | | Iceland | ✓ | | India | ✓ | | Indonesia | ✓ | | Iran | ✗ | | Iraq | ✗ | | Ireland | ✓ | | Isle of Man | ✓ | | Israel | ✓ | | Italy | ✓ | | Jamaica | ✓ | | Japan | ✓ | | Jersey | ✓ | | Jordan | ✓ | | Kazakhstan | ✓ | | Kenya | ✓ | | Kiribati | ✓ | | Kosovo | ✓ | | Kuwait | ✓ | | Kyrgyzstan | ✓ | | Laos | ✓ | | Latvia | ✓ | | Lebanon | ✓ | | Lesotho | ✓ | | Liberia | ✓ | | Libya | ✓ | | Liechtenstein | ✓ | | Lithuania | ✓ | | Luxembourg | ✓ | | Macau | ✓ | | Macedonia | ✓ | | Madagascar | ✓ | | Malawi | ✓ | | Malaysia | ✓ | | Maldives | ✓ | | Mali | ✓ | | Malta | ✓ | | Marshall Islands | ✓ | | Martinique | ✓ | | Mauritania | ✓ | | Mauritius | ✓ | | Mayotte | ✓ | | Mexico | ✓ | | Micronesia | ✓ | | Moldova | ✓ | | Monaco | ✓ | | Mongolia | ✓ | | Montenegro | ✓ | | Montserrat | ✓ | | Morocco | ✓ | | Mozambique | ✓ | | Myanmar (Burma) | ✓ | | Namibia | ✓ | | Nauru | ✓ | | Nepal | ✗ | | Netherlands | ✓ | | New Caledonia | ✓ | | New Zealand | ✓ | | Nicaragua | ✓ | | Niger | ✓ | | Nigeria | ✓ | | Niue | ✓ | | Norfolk Island | ✓ | | Northern Mariana Islands | ✓ | | North Korea | ✗ | | Norway | ✓ | | Oman | ✓ | | Pakistan | ✓ | | Palau | ✓ | | Palestine | ✓ | | Panama | ✓ | | Papua New Guinea | ✓ | | Paraguay | ✓ | | Peru | ✓ | | Philippines | ✓ | | Pitcairn | ✓ | | Poland | ✓ | | Portugal | ✓ | | Puerto Rico | ✓ | | Qatar | ✓ | | Republic of the Congo | ✓ | | Réunion | ✓ | | Romania | ✓ | | Russia | ✗ | | Rwanda | ✓ | | Saint Barthélemy | ✓ | | Saint Helena, Ascension and Tristan da Cunha | ✓ | | Saint Kitts and Nevis | ✓ | | Saint Lucia | ✓ | | Saint Martin (French part) | ✓ | | Saint Pierre and Miquelon | ✓ | | Saint Vincent and the Grenadines | ✓ | | Samoa | ✓ | | San Marino | ✓ | | São Tomé and Príncipe | ✓ | | Saudi Arabia | ✓ | | Senegal | ✓ | | Serbia | ✓ | | Seychelles | ✓ | | Sierra Leone | ✓ | | Singapore | ✓ | | Sint Maarten | ✓ | | Slovakia | ✓ | | Slovenia | ✓ | | Solomon Islands | ✓ | | Somalia | ✓ | | South Africa | ✓ | | South Georgia and the South Sandwich Islands | ✗ | | South Korea | ✓ | | South Sudan | ✗ | | Spain | ✓ | | Sri Lanka | ✓ | | Sudan | ✗ | | Suriname | ✓ | | Svalbard and Jan Mayen | ✓ | | Sweden | ✓ | | Switzerland | ✓ | | Syria | ✗ | | Taiwan | ✓ | | Tajikistan | ✓ | | Tanzania | ✓ | | Thailand | ✓ | | Timor-Leste | ✓ | | Togo | ✓ | | Tokelau | ✓ | | Tonga | ✓ | | Trinidad and Tobago | ✓ | | Tunisia | ✗ | | Turkey | ✗ | | Turkmenistan | ✓ | | Turks and Caicos Islands | ✓ | | Tuvalu | ✓ | | Uganda | ✓ | | Ukraine | ✓ | | United Arab Emirates | ✓ | | United Kingdom | ✓ | | United States | ✓ | | United States Virgin Islands | ✓ | | Uruguay | ✓ | | U.S. Minor Outlying Islands | ✗ | | Uzbekistan | ✓ | | Vanuatu | ✓ | | Vatican City (Holy See) | ✓ | | Venezuela | ✗ | | Vietnam | ✓ | | Wallis and Futuna | ✓ | | Western Sahara | ✓ | | Yemen | ✓ | | Zambia | ✓ | | Zimbabwe | ✓ | ### KYC requirements for end users There are two KYC levels: 1. Non-document KYC (LKYC) allows customers to make NFT purchases of up to $5,000 US. These are lifetime limits per customer profile. Once a customer reaches the applicable limit, they will need to complete document KYC to continue making purchases. LKYC requires only the customer’s name, date of birth, and billing address. In most cases, it is completed within a few seconds, although it may take longer if manual review is required. 2. Document KYC (FKYC) allows customers to make NFT purchases of up to $20,000 US per week. Customers must provide proof of identity (such as a passport or driver’s license), proof of address dated within the last three months (such as a bank statement or utility bill), and complete a liveness check similar to a video selfie. For US residents, FKYC may also be completed by submitting only a driver’s license together with the liveness check. In most cases, FKYC is completed within a few seconds, although it may take longer if manual review is required. ### Minimum and maximum purchase values The minimum purchase amount is $1 US. The maximum purchase amount is $20,000 US, subject to the customer’s applicable [KYC limit](#kyc-requirements-for-end-users).