NFT invoice payment method integration guide

This guide explains how to integrate the NFT invoice payment method with txn, from initial setup through successful payment confirmation.

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 the Txn-hosted payment page

5. Receive invoice status updates by webhook

6. Mark the payment as successful once the invoice reaches completed

Hosted page is required. You must redirect your end users to the Txn-hosted payment page (hostedPageUrl) returned in the invoice response. Embedding it in an iframe, webview, or any other inline frame is not permitted. Open it in a new browser tab or redirect the user's current tab to the URL.

Advertise this only as an NFT purchase — never as a card payment. Present this method to your end users as an NFT purchase. Do not label, describe, or market it as a card payment anywhere on your website, checkout, or user flow — including any use of "card", "credit/debit card", "pay by card", or the Visa and Mastercard names, logos, or branding.

To create the invoice request itself, use the standard Create Invoice API described here:

Creating invoice

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.

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:

Authorization: Bearer <api_key>
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:

POST /api/public/v1/invoices

For this payment method, the following attributes must always be set exactly as shown below.

Required NFT parameters

Production

{
  "chargedCurrency": "USDC",
  "network": "polygon:usdcv2",
  "paymentMethods": ["nft"]
}

Sandbox

{
  "chargedCurrency": "POL",
  "network": "tpolygon",
  "paymentMethods": ["nft"]
}

These values are required for NFT and should not be changed.

4. Example requests

Production example

curl -X POST "https://api.txn.io/api/public/v1/invoices" \
  -H "Authorization: Bearer <production_api_key>" \
  -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"
      }
    }
  }'

Sandbox example

curl -X POST "https://api.sandbox.txn.io/api/public/v1/invoices" \
  -H "Authorization: Bearer <sandbox_api_key>" \
  -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"
      }
    }
  }'

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:

"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.

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.