public-api-docs

User API Payments And Invoices Guide

Overview

Payment and invoice endpoints support user-managed payment sources, wallet integrations, default payment selection, source deletion, invoices, and invoice downloads. Use them when building billing profile screens, checkout flows, rental/booking payment readiness, and invoice history.

Related reference: User API User API Guide Commercial Products Guide Wallet And Balances Guide Error Codes

Core Concepts

Payment Sources

A payment source is a user payment method such as card, Apple Pay, Google Pay, PayPal, or another provider-specific method configured for the tenant. Available methods depend on the branch, payment service provider, and tenant configuration.

Payment Gateways And Methods

The main payment gateways used for User API payment-method setup are Stripe and Adyen. The User API exposes stable payment-method endpoints, while the tenant’s billable branch configuration decides which gateway is used behind those endpoints.

Gateway Credit card Apple Pay Google Pay PayPal Notes
Stripe Supported through GET /payment/cc and POST /payment/cc. Not exposed through the legacy Stripe User API gateway path. Not exposed through the legacy Stripe User API gateway path. Not exposed through the legacy Stripe User API gateway path. The card setup response includes Stripe client configuration such as the public key.
Adyen Supported through GET /payment/cc and POST /payment/cc. Supported through POST /payment/applepay. Supported through POST /payment/googlepay. Supported through POST /payment/paypal. Card setup can require 3DS. PayPal returns provider-specific authorization information.

Other gateway implementations exist in the platform, including the generic payment-gateway-service integration, but Stripe and Adyen are the primary gateways to plan around for public User API integrations unless Wunder Mobility confirms a different tenant-specific setup.

Payment sources have a state. The most important states for app flows are:

State Meaning
ACTIVE The source can be used for payment flows.
PENDING The source was created but is not fully confirmed yet. Poll or re-fetch after the provider flow completes.
ACTION_NEEDED The user or app must complete a provider action such as redirect, authorization, or challenge.
FAILED Source creation failed. Show a retry or alternative payment method.
CANCELLED The source was canceled or removed.

Redirect And Async Flows

Some payment methods need redirects, 3DS, or asynchronous confirmation from the payment gateway service. After adding a payment source, re-fetch GET /payment to show final source state and default selection.

Default Payment Source

Users can change their default payment source. Rental, booking, package, subscription, deposit, and balance workflows can depend on a valid default payment method.

For personal rentals, the app switches payment method by changing the default payment source before rental creation:

  1. Load sources with GET /payment?state=ACTIVE&branchId={branchId}.
  2. Show the current default source and the other eligible sources on the rental start screen.
  3. When the user selects another source, call PUT /payment with { "sourceId": "{paymentSourceId}" }.
  4. Re-fetch GET /payment and only then call POST /rentals.

Do not pass a card, wallet, or PayPal source ID to POST /rentals. The rental endpoint does not select a personal payment source directly; it uses the user’s current eligible default source for personal billing. If the user chooses a business account instead, select the billing context on the rental request with userGroupCode and type: "BUSINESS" where applicable.

Common User Workflows

List And Manage Payment Sources

Task Endpoint
List payment sources GET /payment
Change default payment source PUT /payment
Delete payment source DELETE /payment

Do not delete a source while another payment, deposit, rental, booking, or subscription flow is actively depending on it unless the API allows it.

Add Payment Sources

Task Endpoint
Initialize card addition GET /payment/cc
Add credit card POST /payment/cc
Add Apple Pay POST /payment/applepay
Add Google Pay POST /payment/googlepay
Add PayPal POST /payment/paypal

The Core User API coordinates with the payment gateway service, which abstracts PSP-specific source creation, redirect handling, webhooks, and source state updates. App integrations should follow the redirect or provider-specific instructions returned by the User API rather than calling the payment gateway service directly.

Add A Credit Card

Credit-card setup is usually a provider-token flow:

  1. Call GET /payment/cc, passing branchId and userGroupId when relevant. The response contains provider-specific setup information, such as SDK configuration or a client token.
  2. Collect card details through the PSP-approved client SDK or hosted component. Do not send raw card details to the User API.
  3. The provider returns a token or encrypted payment payload.
  4. Call POST /payment/cc with the token. Include branchId when payment configuration is branch-specific and userGroupId when adding a business-account payment source.
  5. If the response is 204 No Content, source creation completed. Re-fetch GET /payment?state=ACTIVE&branchId={branchId} and show the new source.
  6. If the response is 200 OK, additional authentication is required. The response contains provider-specific 3DS or redirect payload. Complete that challenge in the app or browser.
  7. After the redirect/challenge finishes, re-fetch GET /payment with suitable state filters. Show ACTIVE, PENDING, ACTION_NEEDED, or FAILED based on the returned source state.
  8. If the new source should be the default, call PUT /payment with the source ID, then re-fetch GET /payment.

The app should not assume that POST /payment/cc always finishes synchronously. Card flows can be immediate, 3DS challenge-based, redirect-based, or fail before a usable source is created.

Add Wallets Or PayPal

Apple Pay and Google Pay use the platform wallet SDK first, then the User API:

  1. Confirm the method is available for the user device, branch, and tenant configuration.
  2. Collect the wallet token through Apple Pay or Google Pay.
  3. Call POST /payment/applepay or POST /payment/googlepay with the token.
  4. A 204 No Content response means the source was accepted. Re-fetch GET /payment.

PayPal starts as an authorization flow:

  1. Call POST /payment/paypal, passing branchId and userGroupId where relevant.
  2. Use the returned provider-specific information to send the user through PayPal authorization.
  3. After the provider callback/redirect completes, re-fetch GET /payment.

Payment Readiness Before Core Flows

Rental start, booking pickup, package purchase, subscription purchase, deposits, and outstanding-balance settlement can all depend on payment readiness. A practical app flow is:

  1. Load current payment sources with GET /payment.
  2. If no active usable source exists, send the user to payment setup before the rental, booking, package, or subscription action.
  3. If a source is ACTION_NEEDED or PENDING, resume or explain the provider flow instead of creating another source immediately.
  4. After payment setup, re-run the original requirement check or retry the original business action.

On rental start screens, combine payment readiness with business-account selection:

User selection What to call How billing is selected
Personal payment GET /payment, optionally PUT /payment, then POST /rentals Current eligible default payment source.
Newly added personal payment Add the source, re-fetch GET /payment, optionally PUT /payment, then POST /rentals New source after it becomes active and default.
Business account GET /groups, GET /rentals/requirements with group context, then POST /rentals with userGroupCode Business account billing configuration.

Payment source setup can be branch-specific or group-specific. Include branchId and userGroupId in payment setup and management calls when the configuration is scoped that way.

Review Invoices

Task Endpoint
List current user’s invoices GET /invoices
Retry unpaid invoice payment POST /invoices/retry
Download invoice GET /invoices/{invoiceId}/download

Use invoice listing for user billing history. Use invoice downloads for the user-facing PDF or downloadable invoice artifact.

Show And Pay Unpaid Invoices

Use GET /invoices?unpaid=true&invoicedOnly=true when the app needs to show an unpaid-invoice banner, account warning, or billing screen. For business-account invoices, include userGroupId.

Example:

GET /invoices?unpaid=true&invoicedOnly=true

Render each returned invoice using the user-facing fields:

Field How to use it
invoiceState Display state. PAYMENT_FAILED, DUE, and OVER_DUE should be shown as actionable unpaid states.
isRetryable Show a pay/retry button only when this is true.
price, currency Show the amount due.
title, invoiceDate, dueDate Show the invoice context and due date where available.
paymentDetails Explain which payment method failed or was used, if present.

When the user taps an unpaid invoice, open an invoice detail screen with the invoice amount, state, due date, payment method, and a CTA:

POST /invoices/retry?invoiceIds=12345

The retry endpoint returns 204 No Content when the retry request was accepted. After calling it, re-fetch:

GET /invoices?unpaid=true&invoicedOnly=true

If the invoice disappears from the unpaid list or returns with invoiceState=SETTLED, show it as paid. If it remains PAYMENT_FAILED, keep the CTA visible and show the current payment failure state. If the user has no active payment source or the payment source is outdated, route them through payment setup first with GET /payment, GET /payment/cc, and the relevant add-payment endpoint.

You can also retry all retryable unpaid invoices at once by calling:

POST /invoices/retry

Use this for a “Pay all outstanding invoices” action only if the UI clearly explains that multiple invoices may be charged.

Unpaid invoices can also appear as a rental requirement failure. If GET /rentals/requirements returns USER_HAS_NO_UNPAID_INVOICES with fulfilled=false, link the user to the unpaid-invoices screen and load GET /invoices?unpaid=true&invoicedOnly=true.

Most Relevant APIs

Area Endpoints
Payment sources GET /payment, PUT /payment, DELETE /payment
Cards and wallets GET /payment/cc, POST /payment/cc, POST /payment/applepay, POST /payment/googlepay, POST /payment/paypal
Invoices GET /invoices, POST /invoices/retry, GET /invoices/{invoiceId}/download

Implementation Notes