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

Doing this by hand instead of by code? See manually adding a transaction for the same delivery from the panel.

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 Uploading and managing 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": "[email protected]", "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. See Viewing specific order details for what that record looks like in the panel.

Troubleshooting

Symptom	Cause	Action
422 naming a field	One of the six required fields is missing or malformed	amount accepts digits with up to two decimals; recheck the field named in the response
422 about a template	No default template is set	Set one in Templates, or pass template_id
The buyer received two emails	The call was sent twice	Use the returned id to make retries safe, and never retry a call that already returned 200
Nothing delivered and quantity_sent stays 0	The database has no available codes, or the account has no credits	Check both before retrying

If it still is not working

Submit a ticket with the transaction id and the buyer's email.