Your first sale

Before your first sale: today a sale happens in Brazil (you and the buyer in Brazil), by Pix or card (single payment), both in test environment. The charge lands on your receiving account at the payment provider. International sales, with Infi UK Ltd as the merchant of record, are coming soon. See going to production.

Which path is yours

	What you build	When to use
Payment link	nothing	One-off sale, charging over WhatsApp, a first sale before an app exists
Invoice + `charge`	the “Buy” button and a return page	You have an app and want the buyer inside your flow, without building a payment screen

Both end in the same place: the buyer pays on Infi’s checkout page (/pay/...), which shows the Pix QR or the card form. Both end in the same invoice and the same webhook. The difference is how much of the experience is yours.

When in doubt, start with the link. It is the only one that asks nothing of your app. You can switch later: the product and the catalog are the same.

The middle path, end to end

Assuming you already have a published product (see the catalog), a key and an account ready to receive:

# 1. create your customer's invoice
INV=$(curl -s -X POST $API/billing/products/$PID/invoices \
  -H "Authorization: Bearer $K" -H 'Content-Type: application/json' -H "$(IDEM)" \
  -d '{"customer":{"externalId":"u1","email":"u1@x.com","taxId":"52998224725"}}' | jq -r .id)

# 2. STORE THIS. It is the step nobody documents and everybody forgets.
#    (in your database: invoiceId -> your user, status "open")

You must map invoiceId → your user. We do not know who your user is: you pass an externalId and we hand back an invoiceId. When the payment confirms, the webhook carries the invoiceId, not your user. If you did not store the pair, you received money and do not know from whom.It is the most important architecture decision on this page and it fits in one row of a table in your database.

Charging: what `charge` returns

curl -s -X POST $API/pay/$SLUG/invoices/$INV/charge \
  -H 'Content-Type: application/json' -H "$(IDEM)" -d '{"method":"pix"}'

The response carries what the buyer needs to finish, such as the Pix QR code, and the flow stays on Infi’s checkout page. status comes back pending.

Do not trust the buyer’s return. They may come back without having paid, or never come back. The webhook is what confirms; the return query string never proves anything.

Knowing it was paid

Do not trust the return of charge: it comes back pending. Payment is asynchronous, and the confirmation arrives by webhook (payment.confirmed, invoice.paid).

# sandbox: polling, because registering a webhook answers 503
curl -s $API/pay/$SLUG/invoices/$INV | jq .invoice.status   # "open" | "paid"

When it confirms, use the event’s invoiceId to find the order you stored in step 2. Details in webhooks.

The buyer clicked “Buy” twice

Every non-GET method on the authenticated API requires an Idempotency-Key (the public /pay/* routes, which the buyer’s browser calls, do not). It is what stops two clicks from becoming two invoices.

# the SAME key for the SAME purchase intent
KEY="order-$USER_ID-$PID-$(date +%F)"

curl -s -X POST $API/billing/products/$PID/invoices \
  -H "Authorization: Bearer $K" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $KEY" -d '{"customer":{"externalId":"u1","email":"u1@x.com","taxId":"52998224725"}}'

Same key, same body → you get the original response back. One invoice.
Same key, different body → 409 idempotency_key_reused. It is protection: it means you reused the key for something else.
No key → 400 idempotency_key_required.

A fresh key on every call protects against a network retry, not against a double click. For the double click, the key must come from something stable in your intent, as in the example above.

The simplest thing is not to let them click twice. Disable the button on the first click and treat the Idempotency-Key as the safety net, not the first line of defense.

Before selling: the name the buyer sees

Your tenant is born with a placeholder name. If you do not change it, the checkout and the payment link literally say “New app”, and nobody buys from a store called New app.

await infi.account.update({ name: "Orvalho Coffee" });
// optional, cited in the payment mandate:
await infi.account.update({ termsUrl: "https://orvalhocoffee.com/terms" });

It takes effect at once, with no product republish and no new link: the same link shows the new name. infi.account.get() reads it back. (From @beinfi/sdk@0.10.7; before that it is PATCH /account/tenant.)

Sold. Now deliver

If what you sell is a file or access, do not build that by hand: attach the deliverable to the product and Infi sends the buyer a personal link when the payment confirms, and hands you the same link to show on your thank-you page. It is in delivering the product. The buyer’s side (finding out they paid, delivering, and the two polls nobody guesses) is in the thank-you page.

Get started

Integration

Your first sale

Which path is yours

The middle path, end to end

Charging: what `charge` returns

Knowing it was paid

The buyer clicked “Buy” twice

Before selling: the name the buyer sees

Sold. Now deliver

​Which path is yours

​The middle path, end to end

​Charging: what charge returns

​Knowing it was paid

​The buyer clicked “Buy” twice

​Before selling: the name the buyer sees

​Sold. Now deliver

Which path is yours

The middle path, end to end

Charging: what `charge` returns

Knowing it was paid

The buyer clicked “Buy” twice

Before selling: the name the buyer sees

Sold. Now deliver