Skip to content

Partner Card API Changelog ​

Release notes for the Partner Card API. Dates reflect production availability at api.agiodigital.com/partner/cards/graphql. Changes land on the development environment (dev.api.agiodigital.com) first — test there before relying on new capabilities in production.

2026-11-17 ​

  • Occupation: code preferred. occupation still accepts a SOC code or its title; codes are preferred. An invalid value returns CARD_INVALID_REQUEST with extensions.field: "occupation", also when the card program refuses it. Not breaking. See Occupation codes.

2026-11-16 ​

  • New issuer refusal code. updatePartnerCardUserContact now answers CARD_ISSUER_REJECTED when the card issuer does not accept the update. The meaning is unchanged. See Errors.
  • New decidedBy value. In the card_wallet.* events, decidedBy is now card_issuer for an issuer decision. The meaning is unchanged.
  • Hub access and roles guide. A new page covers partner roles, organization members and who can move funds. See Hub access and roles.
  • Card-to-card transfers. cardTransferForPartner moves collateral from one of your cardholders to another. See Transfer between cardholders.

2026-11-12 ​

  • Treasury funding: idempotency key and cancel. cardFundSubClientFromTreasury accepts an optional idempotencyKey. A repeat call with the same key returns the first job and creates no new one. cardFundSubClientCancel makes a failed job final. New codes: INVALID_IDEMPOTENCY_KEY, IDEMPOTENCY_KEY_REUSED, NOT_CANCELLABLE, FUNDING_EXPIRED, FUNDING_NOT_SENT, and the status cancelled. Details: Card funding.

2026-11-06 ​

  • Apple Pay and Google Pay results. New webhook events card_wallet.provisioned, card_wallet.provisioning_declined and card_wallet.token_changed report each wallet decision, with the reason and what the cardholder can do. AgioCard_card_wallet_event holds the history, and token_wallets on AgioCard_card now lists the wallets reported as added. See Wallet events.

2026-11-04 ​

  • Choose when a card is issued. createCardApplicationForPartnerUser has a new optional autoIssueCard, default true: approval creates a card, as it does today. Set autoIssueCard: false to create no card at approval and issue it with createCard at the point your flow needs it, such as after payment. If you call createCard after every approval, set it to false, because otherwise each cardholder gets two cards. See Submit an application.
  • Read your treasury balance. AgioCard_vw_partner_wallet now also returns your own organization's smart wallets, including your treasury, and token_balances lists what each one holds when your treasury is enabled. AgioCard_vw_partner_wallet_token_balance gains those holdings as new rows with a null advance_rate. If you sum that view to get cardholder collateral, exclude those rows. Existing rows are unchanged. See Read your treasury balance.

2026-10-30 ​

  • Agreement set bumped to 2026-10-30.1. Updated Authorized User Agreement. Consumer documents and their documentHashes are unchanged; 2026-08-24.1 stays accepted.
  • Verification links are valid for 24 hours. Don't store completionUrl for later. When the cardholder opens it, call refreshCardApplicationCompletionLink for a fresh link. A refresh can emit card_application.completion_link_changed.
  • Stable continueUrl for stored links. When available, continueUrl is returned with completionUrl and stays valid for 14 days; each open serves a fresh link. Store it instead of completionUrl when present.

2026-10-27 ​

  • New events card_transaction.created and card_transaction.updated for every transaction type. Subscribe with CARD_TRANSACTION_CREATED and CARD_TRANSACTION_UPDATED. They fire for spend, collateral, payment and fee rows, including the payment and fee rows that the four lifecycle events never emitted, for rows that carry a card application. Collateral rows recorded against a company only are not emitted. created fires when a row is first recorded; updated fires when status, amount, authorizedAmount, authorizationUpdateAmount, declinedReason or postedAt changes. The payload is the usual transaction record plus previousStatus and previousAmount. A partner subscribed to both card_transaction.settled and card_transaction.updated receives both for one settlement, with the same cardTransactionExternalId. Deduplicate by eventId, upsert by cardTransactionId, and apply an update only when its updatedAt is newer. If your code switches on eventName, add both values. See Generic transaction events.

2026-10-21 ​

  • Invalid occupation on createCardApplicationForPartnerUser now returns CARD_INVALID_REQUEST. A value that is not a valid SOC occupation description (for example Engineer) used to fail with the generic CARD_API_ERROR ("Card operation failed. Please try again."). The request fails before any issuer call, with the same GraphQL error shape, now carrying the message Invalid occupation: "<value>". Must be a valid SOC occupation description., extensions.field: "occupation" and extensions.suggestions. The request failed before and still fails; every successful request is unchanged. Retrying with the same value cannot succeed, so correct the occupation instead of retrying.

2026-10-12 ​

  • Phone pair normalization widened before the validation above applies. createPartnerCardUser and patchPartnerCardUser now also normalize spacing, punctuation (dots, dashes, parentheses), invisible/full-width characters, a 00 international-dialing prefix, and a duplicated country code combined with a trunk 0. Only a pair that stays invalid after normalization still warns (until 2026-10-26) or returns VALIDATION_ERROR. See Provision a cardholder.

2026-10-09 ​

  • Phone number validated against its country code before the issuer call. createPartnerCardUser and patchPartnerCardUser now confirm phoneCountryCode and phoneNumber form a valid number together instead of forwarding a mismatched pair to the issuer. A phoneNumber with a stray leading +, a repeated country code, or a leftover national trunk 0 is normalized rather than rejected. Launch period: from deploy an invalid pair returns success with a warning field naming the fields and the fix; from 2026-10-26 it returns success: false with errorCode: "VALIDATION_ERROR". Fix: send phoneNumber as the national number only (no country code, no leading 0/+) and phoneCountryCode as digits only. See Provision a cardholder.

2026-10-07 ​

  • New application statuses NOTSTARTED and TOSNOTACCEPTED. The issuer added two application states: the cardholder has not started the application, or has not accepted the terms of service. Both now appear as applicationStatus values and in the CardApplicationStatus enum. card_application.status_changed reports them with nextStep: AWAIT_REVIEW and a completionUrl to give the cardholder. completionUrl is now set for NEEDSINFORMATION, NEEDSVERIFICATION, NOTSTARTED, and TOSNOTACCEPTED, and stays null for every other status. If your code switches on status, add both values. See Check application status.

2026-09-22 ​

  • card_application.status_changed now carries completionUrl. The event told you a cardholder had to act but not where to send them, so every remediable pause needed a follow-up query to find the verification link. The data block now includes completionUrl, the composed and signed link to the hosted verification page. It is populated only while the application waits on the cardholder (NEEDSINFORMATION / NEEDSVERIFICATION) and reads null on every other transition, including MANUALREVIEW, which waits on Agio compliance. A settled or held application never re-advertises its last remediation link. Open it as-is. The field is additive: every existing field keeps its behavior. See Delivery format.

2026-09-15 ​

  • application_completion_link.url now carries the complete signed link. Correction: The original announcement above described a change that broke compatibility. The correction adds completionUrl only and preserves each existing field's original behavior. The hosted verification page requires a signed link. Status updates retain the original url and params. Records from application creation retain their composed url without params. The new completionUrl field contains the composed link. If completionUrl is present, open it as-is. Older records can lack this field until their next status update. For those records, append every available key in params to url as a query parameter. If params is absent, open url as-is. Existing integrations that compose the link need no change. See Application lifecycle.

2026-08-24 ​

  • Agreement set bumped to 2026-08-24.1. Formatting-only fix to the International Card Terms: the fees block (foreign purchase and penalty fees) now renders as regular text instead of a raw code block. No terms, fees, or rights changed. 2026-08-21.1, 2026-07-26.1, and 2026-07-24.1 all stay accepted, so no partner is forced to change. If you present the international terms, re-fetch the canonical document and recompute its sha256 at your next convenient change.

2026-08-21 ​

  • Agreement set bumped to 2026-08-21.1. The International Card Terms (card-terms-international) gain section 8.4, Cardholders in Nigeria: BANEX MICROFINANCE BANK LIMITED, licensed by the Central Bank of Nigeria, markets the card and owns CBN and Nigeria Data Protection Act compliance, while Agio handles customer service. No other document changed. 2026-07-26.1 and 2026-07-24.1 stay accepted, so no partner is forced to change. If you present the international terms, re-fetch the canonical document and recompute its sha256. See Consent attestation.

2026-08-14 ​

  • Card name fields validated before the issuer call. createCard now rejects invalid displayName and shipping.firstName / shipping.lastName values with a VALIDATION_ERROR naming the field, the allowed pattern, and the offending characters, replacing the generic CARD_API_ERROR. displayName matches ^[a-zA-Z0-9 .-]+$ (max 26 characters); shipping names match ^[a-zA-Z -]+$ (max 50). Accented and non-Latin characters are rejected: transliterate to ASCII ("Renée" becomes "Renee") before submitting. No card is created on a validation failure, so a corrected retry is always safe. See the error reference.

2026-08-04 ​

  • card_application.status_changed gains nextStep and reasonDescription. Both are optional and additive, so a receiver that ignores them behaves as before. nextStep is RESUBMIT, AWAIT_REVIEW, TERMINAL, or null, and tells you whether the cardholder can correct and retry, whether a decision is still pending, or whether the outcome is final. reasonDescription carries a reviewer comment when one is present, which is uncommon, so do not depend on it being populated. See the updated delivery shape.

2026-07-29 ​

  • Agreement set bumped to 2026-07-26.1. The only change is Agio's registered office address, now 45 West Bay Street, Manx Corporate Centre, 4th floor, Nassau, New Providence, The Bahamas. It affects card-terms-us, privacy-policy, and terms-of-use. No terms, fees, or rights changed. 2026-07-24.1 is still accepted, so partners on it need no change. Going forward, the previous agreement version stays accepted alongside each new one, so a version bump will not break an in-flight integration.

2026-07-24 ​

  • Reference table for all agreement documents separated from the selection guide. The full document list (all program types) is now its own labeled reference section, distinct from the per-residency selection table. See Consent attestation.
  • Agreement selection clarified. The document list is a catalog, not a cumulative set. US cardholders accept the US Card Terms and US Account Opening Privacy Notice; non-US cardholders accept the International Card Terms. card_company_id does not change the application type. See Consent attestation.

2026-07-20 ​

  • Canonical agreement documents published for hashing. Each document in agreementsAcceptance.documentHashes is now served as raw markdown at its own https://www.agiodigital.com/<slug>.md URL. Fetch the document and SHA-256 its bytes to produce the sha256 you relay — the guide lists the documentHashes key → URL mapping. See Consent attestation.

2026-07-17 ​

  • Consent attestation added to createCardApplicationForPartnerUser. New agreementsAcceptance input relays verifiable evidence of cardholder consent (agreement version, document hashes, acceptance timestamp). From 2026-07-20 this field is required — omitting it returns errorCode: "ATTESTATION_REQUIRED"; invalid evidence fails with a validation error. isTermsOfServiceAccepted remains for backward compatibility but is now legacy. See Consent attestation.

2026-07-13 ​

  • payment events now carry postedAt. card_transaction.* deliveries and AgioCard_card_transaction rows with transactionType: "payment" now populate postedAt on posting; it previously shipped null on every payment row. Historical rows were backfilled from the original webhook payload where the processor had already reported a posted date.
  • cardCompanyId now derived for partner cardholders on all transaction events. card_transaction.* deliveries for partner-cardholder cards now carry a populated cardCompanyId (previously null outside fee rows), derived server-side from the cardholder's card_user/card_application linkage. Historical rows were backfilled the same way. See the updated delivery shape example.
  • Field-availability matrix added. The guide now documents which data fields are populated per transactionType (spend/collateral/payment/fee), including which fields are null by design — see Field availability by transaction type.
  • Collateral and payment event semantics explained. New guide section covering how collateral events originate (your funding and withdrawals — the sign of amount is the direction), how payment events settle accrued card spend automatically from the cardholder's collateral, and the one-balance-many-cards model behind both — see Understanding collateral and payment events.
  • Webhook starter kit updated for per-type card linkage. The starter kit README and demo receiver now reflect that card linkage is spend-only: wallet-level events (collateral/payment) are matched via cardUserId/cardCompanyId, per the field-availability matrix.

2026-07-10 ​

  • New patchPartnerCardUser mutation. Correct a cardholder's PII — including any address field — at any point before an application is submitted. Only the fields you supply change; the address is re-validated as a merged set. See Correct a cardholder before applying.
  • Earlier, clearer onboarding validation. createPartnerCardUser now validates required fields on submission — blank values and malformed country codes return VALIDATION_ERROR naming each field in a single response — and createCardApplicationForPartnerUser returns INCOMPLETE_ADDRESS listing any missing address fields, so issues surface before the application call. See the error reference.
  • Active-card limit documented. The guide now states the per-cardholder active-card limit (3 active cards within a rolling 90-day window on the developer tier) and the error returned when it's reached. See Active-card limit.

2026-07-09 ​

  • Card transaction webhook payload fixed and enriched. card_transaction.* deliveries previously shipped cardId, externalId, and occurredAt as always-null; those fields are replaced by correctly-populated identifiers (cardId, cardExternalId, cardTransactionExternalId, cardUserId, webhookEventId) and the payload now carries the full transaction record — merchant name/location/category, original amount and currency (localAmount/localCurrency, integer minor units), authorizedAt/postedAt, and more — so a delivery is self-sufficient with no follow-up API call. Deliveries now match what your API token can query on AgioCard_card_transaction. See the updated delivery shape.
  • Webhook starter kit updated. The starter kit receiver now demonstrates per-event routing for card_transaction.* events.

2026-07-06 ​

  • createCard reliability in production. The card-program product configuration is now always applied server-side, resolving intermittent createCard failures (body is missing required property 'configuration'). No change is required on your side — continue sending cardApplicationId and cardType as documented.

2026-07-01 ​

  • Card transaction webhooks are live. subscribePartnerWebhook now delivers real-time transaction events alongside application events: CARD_TRANSACTION_AUTHORIZED, CARD_TRANSACTION_SETTLED, CARD_TRANSACTION_DECLINED, and CARD_TRANSACTION_REVERSED. Subscription setup, payload shapes, and signature verification are documented under Webhook subscriptions.
  • Rate limits documented. The guide now includes the full rate-limit reference.

2026-06-19 ​

  • Treasury funding and withdrawals. Partner organizations can fund card programs and withdraw collateral via the API; the new cardFundSubClientStatus query reports sub-client funding status. See Funding cards and Withdrawing collateral.

2026-06-18 ​

  • Batch distributions. New partnerMultisend mutation distributes funds to many cardholders in one call, with smart-wallet lookup support. See Multisend.

2026-06-01 ​

  • Webhook endpoint requirements clarified. Receiving URLs must be publicly reachable; the webhook onboarding guide was expanded accordingly.

2026-05-29 ​

  • Webhook starter kit. Downloadable starter kit with Express and Bun receiver templates, plus a registry of all subscribable event types.

2026-05-26 ​

  • Onboarding additions. createCardApplicationForPartnerUser accepts partnerKycShareToken (share an existing KYC verification) and a createWallet flag to provision a wallet at card signup. Do not pass an organization ID when provisioning cardholders — it is derived from your API client automatically.

2026-05-19 ​

  • Initial general availability of the Partner Card API: HMAC-signed GraphQL endpoint, cardholder onboarding (KYC + application), virtual card issuance, and application webhooks. Start with the Quickstart.

2026-05-15 ​

  • Application tracking. Card application responses now include cardApplicationId for tracking an application through review.