API reference

Implements RFC 6749 §4.4 (client_credentials). Returns a short-lived JWT access token. When the token expires, call this endpoint again with the same clientId + clientSecret to obtain a new one.

• grantType=client_credentials: supply clientId + clientSecret (provisioned out-of-band by Backer).

Errors follow RFC 6749 §5.2 and use HTTP 400:

• invalid_client: unknown clientId or wrong clientSecret.
• unsupported_grant_type: grantType is not one of the supported values.
• invalid_request: grantType missing or otherwise malformed.

This endpoint is unauthenticated – do not send the Authorization header.

Registers a partner customer (registry owner or gift giver) with Backer. Must be called before creating an account or submitting a payment on behalf of the customer.

clientCustomerId is optional. When provided, it must be unique within the partner's namespace.

Looks up a customer by the partner-supplied clientCustomerId, scoped to the calling partner. To fetch by the Backer customer ID instead, use GET /v2/customers/{customerId}.

Updates mutable fields on an existing customer. All fields are optional; at least one must be provided.

Supported updates:

• clientCustomerId – partner's unique identifier for the customer
• email
• firstName
• lastName

Sets a customer's status.

• active – reactivates a customer that is inactive or on hold. Reactivates their accounts (when coming from inactive) or their pending contributions (when coming from on hold).
• inactive – deactivates the customer: cancels their contributions and deactivates their accounts. The customer is not emailed.
• hold – places the customer on hold and opens an internal Backer support ticket for review.

statusReason is required when setting inactive or hold; it is ignored when setting active. A missing reason returns 422 with a statusReason field error (errorCode=missing_value); an unsupported status returns 422 with errorCode=invalid_value.

Returns a short-lived signed URL that authenticates the customer's session on the Backer-hosted payment-method page. Redirect the customer to this URL to collect a card or bank account.

Once collected, the payment method appears in GET /v2/customers/{customerId}/payment-methods.

Customer eligibility:

• Returns 422 with error.errorCode=customer_on_hold when the customer is on hold.
• Returns 422 with error.errorCode=customer_inactive when the customer is inactive.

Removes a saved payment method (card or bank account). Returns the deleted payment method – same shape as GET /v2/customers/{customerId}/payment-methods/{paymentMethodId}.

By default returns plans currently supported for direct linking (isSupported=true). Pass includeUnsupported=true to also include unsupported plans (isSupported=false). Soft-deleted plans are never returned.

By default returns brokerage partners currently supported and enabled for partner linking (isSupported=true). Each broker includes the plans associated with that broker for informational use during broker link flows.

Pass includeUnsupported=true to also include unsupported brokers (isSupported=false), such as partners that are configured but not yet enabled, and catalog-only brokers that are not yet launched. Unsupported brokers cannot be used with validate-account-number / link-account until launched.

Broker-held accounts validate and link against broker-level account number rules. An optional planId on validate-account-number and link-account identifies which underlying 529 plan the customer holds; the plan may have isSupported: false as long as it is in the selected broker's plan catalog and the broker itself has isSupported: true.

Checks whether an account number matches the format expected for a direct 529 plan link and/or a brokerage-held 529 account before calling POST /v2/customers/{customerId}/link-account. Uses the same account-number validation rules as link-account.

At least one of brokerId or planId is required:

• Plan only – planId + accountNumber (the plan must have isSupported: true in GET /v2/plans).
• Broker only – brokerId + accountNumber (the broker must have isSupported: true in GET /v2/brokers).
• Broker + plan – brokerId, optional planId, and accountNumber. planId may be any plan in the broker's catalog from GET /v2/brokers, regardless of the plan's own isSupported value; the broker must have isSupported: true.

Returns 422 with error.errorCode=broker_not_found when brokerId is unknown.

Returns 422 with error.errorCode=broker_not_available when the broker is not currently enabled.

Returns 422 with error.errorCode=broker_plan_mismatch when both brokerId and planId are sent but the plan is not serviced by the broker.

Returns 422 with error.errorCode=plan_not_found when planId is sent but does not match a known plan, or when a plan-only request references a plan whose isSupported value is false.

Returns 422 with error.errorCode=invalid_account_number when the account number does not match the expected format.

Creates a new account for the registry owner identified by customerId and links it to an existing 529 account that the owner has already opened. Use this when the partner has collected the account number out-of-band.

At least one of brokerId or planId is required (same rules as POST /v2/customers/{customerId}/validate-account-number).

Returns 422 with error.errorCode=broker_not_found, broker_not_available, or broker_plan_mismatch for broker validation failures.

Returns 422 with error.errorCode=invalid_account_number when the account number does not match the expected format.

Returns 422 with error.errorCode=plan_not_found when a plan-only link references an unknown or unsupported plan.

If the account number turns out to be invalid (delivered later via a transaction.failed webhook whose failureDetails.code indicates an invalid 529 account number), correct it via POST /v2/accounts/{accountId} once the registry owner provides the right number.

Customer eligibility:

• Returns 422 with error.errorCode=customer_on_hold when the customer is on hold.
• Returns 422 with error.errorCode=customer_inactive when the customer is inactive.

Updates mutable details on a linked 529 account.

Supported updates:

• planId (Backer plan ID with isSupported: true from GET /v2/plans; re-validates the stored account number against the new plan)
• accountNumber (re-validates against the current or updated plan)
• beneficiary.firstName and beneficiary.lastName
• accountOwner.firstName, accountOwner.lastName, and accountOwner.email (overwrites existing values)

At least one update field must be provided.

Returns 422 with error.errorCode=transactions_still_processing when the request changes planId or accountNumber while a contribution push to the 529 plan is scheduled or processing.

Returns 422 with error.errorCode=invalid_account_number when accountNumber or planId fails account-number validation against the target plan.

Sets an account's status.

• active – reactivates a deactivated account.
• inactive – deactivates the account: cancels its contributions. The customer is not emailed.

Deactivating the customer's last account also deactivates the customer.

statusReason is required when setting inactive; it is ignored when setting active. A missing reason returns 422 with a statusReason field error (errorCode=missing_value); an unsupported status returns 422 with errorCode=invalid_value.

Returns the minimum, one-time maximum, and recurring (monthly, annually) maximum contribution amounts (in cents) accepted by the linked 529 plan, for both ACH and card payment methods. Use these to validate amounts client-side before calling POST /v2/payments.

Card maximums are capped at 50000 cents ($500) to reflect the per-transaction card limit; ACH entries return the plan's native limits unchanged.

Returns the platform and processing fees that would be charged for a contribution with the given method and amount, plus the total amount the contributor would be charged (amountInCents + platformFeeInCents + processingFeeInCents).

Returns the platform and processing fees that would be charged for a contribution with the given method and amount, plus the total amount the contributor would be charged. Optional extraItems (amount + tax) are added to totalAmountInCents. Extra-item processing is returned on each item and is not included in totalAmountInCents.

Charges the contributor via the selected payment method and transfers the contribution to the 529 plan.

Response behavior depends on payment method:

• Card: the response immediately indicates success (status: processing) or failure (4xx error envelope).
• ACH: the response confirms the contribution was accepted (status: processing). Collection failures arrive later via a transaction.failed webhook.

Contribution fees:

• Platform Fee is set by the platformFeeInCents parameter.

• Processing Fee is 3% of the amountInCents when the payment method is a card or a digital wallet.

Simulation support (non-production environments only):

• Pass X-Backer-Simulate or use a magic amountInCents value to force deterministic outcomes for partner QA. When both are provided, the amount takes precedence.
• Magic amounts: 4200 successful contribution, 4210 card declined (credit card), 4211 funding insufficient funds (bank account), 4221 provider invalid account number, 4222 provider plan not available, 4230 refund succeeded (any payment method; payout fails, refund succeeds async – refund_processing, refunded), 4231 refund card expired (credit card; payout fails, refund fails async – refund_processing, refunded, refund_failed, code card_expired), 4232 refund account closed (bank account; payout fails, ACH return – refund_processing, refund_failed, code account_closed). Settled, invalid account number, and plan not available work with any payment method.
• Supported header values (same scenarios as magic amounts, plus immediate card decline):
• card_declined: returns an immediate 422 error with error.errorCode=card_declined.
• ach_insufficient_funds: returns a normal 200 processing response, then transitions to failed a few seconds later and emits transaction.failed webhook.
• settled: returns a normal 200 processing response, then a few seconds later simulates settling collecting the funds successfully, sending the funds to the 529 plan successfully and settle the transaction, which emits a transaction.settled webhook.
• invalid_account_number: returns a normal 200 processing response, then a few seconds later simulates collecting the funds successfully but the transfer to the 529 plan fails, which emits a transaction.failed webhook with failureDetails.code=invalid_account_number.
• plan_not_available: returns a normal 200 processing response, then a few seconds later simulates a provider payout rejection with failureDetails.code=plan_not_available.
• refund_succeeded: same as 4230.
• refund_card_expired: same as 4231.
• refund_account_closed: same as 4232.
• In production environments, simulation triggers return 403.

Account/owner eligibility:

• Returns 422 with error.errorCode=account_inactive when the linked account is inactive.
• Returns 422 with error.errorCode=account_owner_on_hold when the account owner is on hold.
• Returns 422 with error.errorCode=account_owner_inactive when the account owner is inactive.
• Returns 422 with error.errorCode=customer_on_hold when the contributing customer (the funding customer) is on hold.
• Returns 422 with error.errorCode=customer_inactive when the contributing customer (the funding customer) is inactive.

Returns a single transaction by its UUID. The response shape is identical to an item in GET /v2/accounts/{accountId}/transactions.

Looks up a transaction by the partner-supplied clientContributionId provided when the contribution was created. To fetch by the Backer transaction ID instead, use GET /v2/transactions/{transactionId}.

Returns the transaction history for a linked 529 account, ordered by descending createdAt. Results are paginated.

Cancels a contribution transaction within the cancellation window.

• ACH: cancels the scheduled bank pull; no refund is needed because funds have not been collected.
• Card: initiates a refund because funds were collected synchronously.

A transaction is cancellable when:

• The current time is within 1 hour 5 minutes of createdAt (cancellableUntil plus a 5-minute backend grace period).

Error codes:

• 409 not_cancellable: transaction is outside the window or otherwise not eligible.

Updates the webhook subscription for the authenticated partner. If the partner has no subscription, returns 404.

All fields are optional; at least one must be provided.

Emitted when a contribution reaches its terminal success state: funds collected from the contributor's payment method and dispatched to the 529 plan. data.object.failureDetails is always null for this event. Payload is signed via the Webhook-Signature header (HMAC-SHA256). Delivery is retried with exponential backoff up to 20 attempts.

Emitted when a contribution transitions to failed (ACH return, plan rejection, card decline, etc.). data.object.failureDetails describes failure phase, category, and reason.

Emitted when a refund is requested for a contribution – for both card and bank (ACH) refunds. This is followed by either transaction.refunded (success) or transaction.refund_failed (failure): card refunds resolve synchronously, while ACH refunds resolve a few business days later once the refund transaction settles or is returned. Payload is signed via the Webhook-Signature header (HMAC-SHA256). Delivery is retried with exponential backoff up to 20 attempts.

Emitted when a refund completes successfully and the contribution is refunded. Card refunds emit this as soon as the refund succeeds; ACH refunds emit it when the refund transaction settles (a few business days later). data.status is refunded and data.failureDetails is absent.

Emitted when a refund attempt fails – a card refund error, or an ACH refund returned by the bank. data.status is always refund_failed. data.failureDetails describes the refund failure (phase=refund).