Appearance
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.
occupationstill accepts a SOC code or its title; codes are preferred. An invalid value returnsCARD_INVALID_REQUESTwithextensions.field: "occupation", also when the card program refuses it. Not breaking. See Occupation codes.
2026-11-16
- New issuer refusal code.
updatePartnerCardUserContactnow answersCARD_ISSUER_REJECTEDwhen the card issuer does not accept the update. The meaning is unchanged. See Errors. - New
decidedByvalue. In thecard_wallet.*events,decidedByis nowcard_issuerfor 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.
cardTransferForPartnermoves collateral from one of your cardholders to another. See Transfer between cardholders.
2026-11-12
- Treasury funding: idempotency key and cancel.
cardFundSubClientFromTreasuryaccepts an optionalidempotencyKey. A repeat call with the same key returns the first job and creates no new one.cardFundSubClientCancelmakes a failed job final. New codes:INVALID_IDEMPOTENCY_KEY,IDEMPOTENCY_KEY_REUSED,NOT_CANCELLABLE,FUNDING_EXPIRED,FUNDING_NOT_SENT, and the statuscancelled. Details: Card funding.
2026-11-06
- Apple Pay and Google Pay results. New webhook events
card_wallet.provisioned,card_wallet.provisioning_declinedandcard_wallet.token_changedreport each wallet decision, with the reason and what the cardholder can do.AgioCard_card_wallet_eventholds the history, andtoken_walletsonAgioCard_cardnow lists the wallets reported as added. See Wallet events.
2026-11-04
- Choose when a card is issued.
createCardApplicationForPartnerUserhas a new optionalautoIssueCard, defaulttrue: approval creates a card, as it does today. SetautoIssueCard: falseto create no card at approval and issue it withcreateCardat the point your flow needs it, such as after payment. If you callcreateCardafter every approval, set it tofalse, because otherwise each cardholder gets two cards. See Submit an application. - Read your treasury balance.
AgioCard_vw_partner_walletnow also returns your own organization's smart wallets, including your treasury, andtoken_balanceslists what each one holds when your treasury is enabled.AgioCard_vw_partner_wallet_token_balancegains those holdings as new rows with a nulladvance_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 theirdocumentHashesare unchanged;2026-08-24.1stays accepted. - Verification links are valid for 24 hours. Don't store
completionUrlfor later. When the cardholder opens it, callrefreshCardApplicationCompletionLinkfor a fresh link. A refresh can emitcard_application.completion_link_changed. - Stable
continueUrlfor stored links. When available,continueUrlis returned withcompletionUrland stays valid for 14 days; each open serves a fresh link. Store it instead ofcompletionUrlwhen present.
2026-10-27
- New events
card_transaction.createdandcard_transaction.updatedfor every transaction type. Subscribe withCARD_TRANSACTION_CREATEDandCARD_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.createdfires when a row is first recorded;updatedfires whenstatus,amount,authorizedAmount,authorizationUpdateAmount,declinedReasonorpostedAtchanges. The payload is the usual transaction record pluspreviousStatusandpreviousAmount. A partner subscribed to bothcard_transaction.settledandcard_transaction.updatedreceives both for one settlement, with the samecardTransactionExternalId. Deduplicate byeventId, upsert bycardTransactionId, and apply an update only when itsupdatedAtis newer. If your code switches oneventName, add both values. See Generic transaction events.
2026-10-21
- Invalid
occupationoncreateCardApplicationForPartnerUsernow returnsCARD_INVALID_REQUEST. A value that is not a valid SOC occupation description (for exampleEngineer) used to fail with the genericCARD_API_ERROR("Card operation failed. Please try again."). The request fails before any issuer call, with the same GraphQL error shape, now carrying the messageInvalid occupation: "<value>". Must be a valid SOC occupation description.,extensions.field: "occupation"andextensions.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.
createPartnerCardUserandpatchPartnerCardUsernow also normalize spacing, punctuation (dots, dashes, parentheses), invisible/full-width characters, a00international-dialing prefix, and a duplicated country code combined with a trunk0. Only a pair that stays invalid after normalization still warns (until 2026-10-26) or returnsVALIDATION_ERROR. See Provision a cardholder.
2026-10-09
- Phone number validated against its country code before the issuer call.
createPartnerCardUserandpatchPartnerCardUsernow confirmphoneCountryCodeandphoneNumberform a valid number together instead of forwarding a mismatched pair to the issuer. AphoneNumberwith a stray leading+, a repeated country code, or a leftover national trunk0is normalized rather than rejected. Launch period: from deploy an invalid pair returns success with awarningfield naming the fields and the fix; from 2026-10-26 it returnssuccess: falsewitherrorCode: "VALIDATION_ERROR". Fix: sendphoneNumberas the national number only (no country code, no leading0/+) andphoneCountryCodeas digits only. See Provision a cardholder.
2026-10-07
- New application statuses
NOTSTARTEDandTOSNOTACCEPTED. The issuer added two application states: the cardholder has not started the application, or has not accepted the terms of service. Both now appear asapplicationStatusvalues and in theCardApplicationStatusenum.card_application.status_changedreports them withnextStep: AWAIT_REVIEWand acompletionUrlto give the cardholder.completionUrlis now set forNEEDSINFORMATION,NEEDSVERIFICATION,NOTSTARTED, andTOSNOTACCEPTED, and staysnullfor every other status. If your code switches on status, add both values. See Check application status.
2026-09-22
card_application.status_changednow carriescompletionUrl. 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. Thedatablock now includescompletionUrl, the composed and signed link to the hosted verification page. It is populated only while the application waits on the cardholder (NEEDSINFORMATION/NEEDSVERIFICATION) and readsnullon every other transition, includingMANUALREVIEW, 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.urlnow carries the complete signed link. Correction: The original announcement above described a change that broke compatibility. The correction addscompletionUrlonly and preserves each existing field's original behavior. The hosted verification page requires a signed link. Status updates retain the originalurlandparams. Records from application creation retain their composedurlwithoutparams. The newcompletionUrlfield contains the composed link. IfcompletionUrlis present, open it as-is. Older records can lack this field until their next status update. For those records, append every available key inparamstourlas a query parameter. Ifparamsis absent, openurlas-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, and2026-07-24.1all stay accepted, so no partner is forced to change. If you present the international terms, re-fetch the canonical document and recompute itssha256at 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.1and2026-07-24.1stay accepted, so no partner is forced to change. If you present the international terms, re-fetch the canonical document and recompute itssha256. See Consent attestation.
2026-08-14
- Card name fields validated before the issuer call.
createCardnow rejects invaliddisplayNameandshipping.firstName/shipping.lastNamevalues with aVALIDATION_ERRORnaming the field, the allowed pattern, and the offending characters, replacing the genericCARD_API_ERROR.displayNamematches^[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_changedgainsnextStepandreasonDescription. Both are optional and additive, so a receiver that ignores them behaves as before.nextStepisRESUBMIT,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.reasonDescriptioncarries 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 affectscard-terms-us,privacy-policy, andterms-of-use. No terms, fees, or rights changed.2026-07-24.1is 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_iddoes not change the application type. See Consent attestation.
2026-07-20
- Canonical agreement documents published for hashing. Each document in
agreementsAcceptance.documentHashesis now served as raw markdown at its ownhttps://www.agiodigital.com/<slug>.mdURL. Fetch the document and SHA-256 its bytes to produce thesha256you relay — the guide lists thedocumentHasheskey → URL mapping. See Consent attestation.
2026-07-17
- Consent attestation added to
createCardApplicationForPartnerUser. NewagreementsAcceptanceinput relays verifiable evidence of cardholder consent (agreement version, document hashes, acceptance timestamp). From 2026-07-20 this field is required — omitting it returnserrorCode: "ATTESTATION_REQUIRED"; invalid evidence fails with a validation error.isTermsOfServiceAcceptedremains for backward compatibility but is now legacy. See Consent attestation.
2026-07-13
paymentevents now carrypostedAt.card_transaction.*deliveries andAgioCard_card_transactionrows withtransactionType: "payment"now populatepostedAton posting; it previously shippednullon every payment row. Historical rows were backfilled from the original webhook payload where the processor had already reported a posted date.cardCompanyIdnow derived for partner cardholders on all transaction events.card_transaction.*deliveries for partner-cardholder cards now carry a populatedcardCompanyId(previouslynulloutsidefeerows), derived server-side from the cardholder'scard_user/card_applicationlinkage. Historical rows were backfilled the same way. See the updated delivery shape example.- Field-availability matrix added. The guide now documents which
datafields are populated pertransactionType(spend/collateral/payment/fee), including which fields arenullby 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
amountis the direction), howpaymentevents 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 viacardUserId/cardCompanyId, per the field-availability matrix.
2026-07-10
- New
patchPartnerCardUsermutation. 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.
createPartnerCardUsernow validates required fields on submission — blank values and malformed country codes returnVALIDATION_ERRORnaming each field in a single response — andcreateCardApplicationForPartnerUserreturnsINCOMPLETE_ADDRESSlisting 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 shippedcardId,externalId, andoccurredAtas 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 onAgioCard_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
createCardreliability in production. The card-program product configuration is now always applied server-side, resolving intermittentcreateCardfailures (body is missing required property 'configuration'). No change is required on your side — continue sendingcardApplicationIdandcardTypeas documented.
2026-07-01
- Card transaction webhooks are live.
subscribePartnerWebhooknow delivers real-time transaction events alongside application events:CARD_TRANSACTION_AUTHORIZED,CARD_TRANSACTION_SETTLED,CARD_TRANSACTION_DECLINED, andCARD_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
cardFundSubClientStatusquery reports sub-client funding status. See Funding cards and Withdrawing collateral.
2026-06-18
- Batch distributions. New
partnerMultisendmutation 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.
createCardApplicationForPartnerUseracceptspartnerKycShareToken(share an existing KYC verification) and acreateWalletflag 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
cardApplicationIdfor tracking an application through review.