Create transactions with the API

Overview

A transaction is a sale Keysender fulfils: it takes codes from a database, sends them to the buyer with your template, and spends one credit per dispatch. Your software creates one whenever it sells outside a connected channel, for example from your own store or a marketplace Keysender does not integrate, and Keysender handles delivery from there.

Before you start

Make sure you have:

• A bearer token from POST /login and the base URL https://panel.keysender.com/api/v1.0.
• A database with available codes (see Upload and manage codes with the API).
• An email template set as the default in Templates, or the template_id of the one to use. Without any template the call is rejected.
• Credits on the account. Each dispatch uses one.

Steps

Record a sale and deliver the code

1. Send POST /transaction/addcustom with the buyer, the quantity, the database, and the sale details:

curl -X POST "https://panel.keysender.com/api/v1.0/transaction/addcustom" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payer": "buyer@example.com", "quantity": 1, "database_id": 123, "amount": 9.99, "currency": "EUR", "name": "Example Game (Steam)"}'

2. Required fields: payer (the buyer's email), quantity (1 to 5,000), database_id, amount (up to two decimals), currency, and name (what the buyer sees). Optional: template_id, msgsubject, and msgtext to override the template for this sale.
3. The response is the transaction: id, status, quantity, quantity_sent, amount, currency, keysender_buyer_email, and keysender_code_id. Delivery runs in the background right after the call, so quantity_sent can still be 0 in this first response.

Send exactly once

1. There is no deduplication key. Every accepted addcustom call creates a new transaction and delivers codes again, even if the body is identical.
2. Record the returned id against your own order before you retry anything, and never retry a call that already returned 200.
3. If a call times out without a response, check the panel's Transactions page for the buyer's email before sending again.

Repeat a previous transaction

1. Send POST /transaction/add with source_transaction_id, payer, quantity, and database_id to create a new transaction with the same details as an earlier one. The source must be an eBay, PayPal Button, or Allegro transaction; other sources are rejected with 422.

Read what was delivered

1. Send GET /transaction/456/inventory with the transaction id. The response lists each delivered code as {"id", "value", "kind"}; for file codes, value is the file encoded in base64 and fileName is added.

Respect the limits

1. Quantity is capped at 5,000 per transaction.
2. Your account may be limited to a number of deliveries per minute; 429 means slow down and retry after a minute.

Confirm it works

The new transaction appears under Transactions in the panel with the buyer's email, the database's available count drops by the quantity, and the buyer receives the delivery email from the template.

If it still is not working

• 422 naming a field: one of the six required fields is missing or malformed; amount accepts digits with up to two decimals.
• 422 about a template: set a default template in Templates or pass template_id.
• The buyer received two emails: the call was sent twice. Use the returned id to stop retries.
• Nothing delivered and quantity_sent stays 0: the database has no available codes, or the account has no credits.
• Still stuck? Submit a ticket with the transaction id and the buyer's email.