Card API Spec
Build one HTTPS endpoint that hands Wire a card for one payment, encrypted so only Wire can read it — the contract your endpoint implements
Early access: paying with a card API is in early access; contact us to enable it for your account. Connecting your endpoint and testing it from the dashboard work today. The pay-time behaviour below is the contract early-access payments follow, so you can build your endpoint against it now.
Wire can pay a bill with a card that your own system issues for that one payment. You don't give Wire access to your vault and Wire stores no card. When a payment starts, Wire calls your endpoint, you answer with the card encrypted to Wire's public key, and Wire forgets it when the job ends.
You build one endpoint. It sits in front of wherever your cards live (a vault, a card issuer, virtual cards) and decides, payment by payment, whether to hand one out.
How it works
You Wire
| 1. POST /v1/wire/task (pay action) |
|------------------------------------------->|
| | 2. signs in to the biller
| 3. GET <your URL>?account=…&amount=… |
|<-------------------------------------------|
| 4. card, encrypted to Wire's public key |
|------------------------------------------->|
| | 5. checks account + amount, pays
| 6. result (webhook or GET /v1/wire/jobs) |
|<-------------------------------------------|Your endpoint is the gate: it can refuse any call it doesn't expect, and you can switch Wire off at any time by revoking the token.
Set up
- Build the endpoint described below, on https, reachable from the public internet.
- Allow-list Wire's IP addresses. They are shown when you connect.
- In the dashboard, open Wire → Identity sources → Connect a vault → Card API and enter your endpoint URL and a bearer token you issue to Wire (or connect it through the API with provider
card_api). The connect form shows Wire's public key (base64 DER): encrypt every card to it. - Wire verifies the connection with one test call (
account=connection-test,amount=0.01), again on every reconnect or token rotation. Answer it as you would any unknown account.
Warning: your endpoint must never issue a real card for
account=connection-test. Refuse it with an error code (for exampleaccount_not_found); otherwise every connect and rotation hands out a real card.
- Test a real answer with Test endpoint on the connected source (see Testing).
Use a separate token, URL and key for staging and production.
The call Wire makes
Made when an early-access payment starts, and by the dashboard test (with a reference that starts with dashboard-test-, unique per test).
GET <your URL>?account=<account_number>&amount=<max_amount>&reference=<payment id>
Authorization: Bearer <token>| Param | Meaning |
|---|---|
account | The account being paid |
amount | The most this payment may charge, including any card fee, as a decimal such as 142.37 |
reference | Your payment id (the task's idempotency_key). Use it to tie the call to your own record |
- One call per payment.
- Wire waits 15 seconds at most, reads at most 64 KB, and never follows redirects (a redirect would carry your token elsewhere).
- Wire only connects to public addresses.
Your answer
A card — HTTP 200:
{ "success": true, "data": { "card": "<compact JWE>" } }card is a compact JWE, alg: RSA-OAEP-256, enc: A256GCM, encrypted to Wire's public key (RSA, 3072 bits or more). Any other algorithm is refused. Other fields in data are ignored. Decrypted, it is:
{
"card_number": "4111111111111111",
"cvv": "123",
"exp_month": "08",
"exp_year": "2029",
"cardholder_name": "ACME",
"billing_address": {
"line1": "12 Main St",
"line2": "Suite 5",
"city": "St. Louis",
"state": "MO",
"zip": "63131",
"country": "US"
}
}card_number, exp_month and exp_year are required. If a biller asks for a field you didn't send (a CVV, a name), the payment fails; Wire never makes one up.
No card — any other answer.
{ "success": false, "error": "<code>", "message": "<text>" }During early-access payments (the dashboard test only reports the step that failed; it never revokes the source):
| Your HTTP status | What Wire does at pay time |
|---|---|
| 401 | Marks the source revoked. Nothing is paid until it is reconnected |
| 403 | Refuses the payment (SOURCE_FORBIDDEN), e.g. your IP allow-list |
| 5xx | Refuses the payment (SOURCE_UNREACHABLE). Send the task again to retry |
429 with no error code | Refuses the payment (SOURCE_THROTTLED) |
| anything else | Refuses the payment with CARD_NOT_ISSUED, and your error code as issuer_code |
Your error code is passed on reduced to lower-case letters, digits and _, 40 characters at most. message is never shown, so keep codes meaningful: no_open_window, amount_too_high, account_not_found.
A refused payment is refused before anything is recorded, so the same idempotency_key can be sent again.
What Wire does with the card
During an early-access payment:
- Holds it in memory for the one job. It is never written to a database, log, screenshot or result, and never shown to the AI model that drives the browser.
- Types it into the biller's payment form and unticks "save this card".
- Stops without paying if the account or the amount on the biller's page does not match the task.
Recommended rules for your endpoint
None are required by Wire. They keep a leaked token or a wrong call from costing you money:
- Open a window per payment. Answer only for an account you just sent a pay task for, for a limited time (for example 30 minutes), and refuse otherwise (
no_open_window). - Cap the amount. Refuse when
amountis above the bill plus a margin for card fees (amount_too_high), and set the card's own spending limit to match, so a bigger charge declines at the network. - Use single-purpose cards. A virtual card per payment, or per biller, limits what any one card can do.
- Allow-list Wire's IPs and keep the token for this endpoint only.
Testing
From the dashboard
On Wire → Identity sources, a connected Card API source has a Test endpoint button (the card icon). Enter an account and an amount and Wire makes one real card request to your endpoint, exactly as a payment would, with a reference that starts with dashboard-test- (a fresh random suffix each test, so idempotency on reference doesn't replay an old card). Wire decrypts the card to check it, then drops it. It shows you only:
- each step, pass or fail: reached your endpoint, token accepted (not 401), our address allowed (not 403), card issued, JWE is
RSA-OAEP-256+A256GCM, decrypts with Wire's key,card_numberpresent (13–19 digits),card_numberpasses Luhn,exp_month/exp_yearvalid and not expired; - which optional fields you sent:
cvv,cardholder_nameand eachbilling_addresspart; - your HTTP status class (
2xx,4xx, …), whenever your endpoint answered; - the card's last four digits;
- on a refusal, your sanitized
errorcode.
The card number, CVV, expiry and your token are never shown or logged. A failing Luhn check is reported, not treated as an error, so a test card (below) passes every other step. A failed test never revokes the source. Treat a reference starting with dashboard-test- as a test call: hand out a test card for it, or refuse it with a code of your choice.
Test cards
Run a staging endpoint that returns a fake card that fails the Luhn check (for example 1234567812345678), encrypted exactly like a real one, so the same decrypt path is tested. The dashboard test reports it as failing Luhn and checks everything else. In early-access payments, Wire accepts such a card only where test cards are switched on, and then the payment is always a dry run: everything up to the pay button, which is never pressed.