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

  1. Build the endpoint described below, on https, reachable from the public internet.
  2. Allow-list Wire's IP addresses. They are shown when you connect.
  3. 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.
  4. 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 example account_not_found); otherwise every connect and rotation hands out a real card.

  1. 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>
ParamMeaning
accountThe account being paid
amountThe most this payment may charge, including any card fee, as a decimal such as 142.37
referenceYour 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 statusWhat Wire does at pay time
401Marks the source revoked. Nothing is paid until it is reconnected
403Refuses the payment (SOURCE_FORBIDDEN), e.g. your IP allow-list
5xxRefuses the payment (SOURCE_UNREACHABLE). Send the task again to retry
429 with no error codeRefuses the payment (SOURCE_THROTTLED)
anything elseRefuses 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.

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 amount is 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_number present (13–19 digits), card_number passes Luhn, exp_month/exp_year valid and not expired;
  • which optional fields you sent: cvv, cardholder_name and each billing_address part;
  • your HTTP status class (2xx, 4xx, …), whenever your endpoint answered;
  • the card's last four digits;
  • on a refusal, your sanitized error code.

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.