Sponge Cards API

openapi: 3.2.0
info:
  title: Sponge public Cards API
  version: 1.0.0
  description: Public REST endpoints for agents, wallets, transfers, payments, cards, MPP, trading, and fiat onramps.
servers:
- url: https://api.wallet.paysponge.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Cards
paths:
  /api/credit-cards:
    post:
      operationId: postApiCreditCards
      tags:
      - Cards
      summary: Store a credit card
      description: Store card details as an encrypted agent payment method for checkout. Prefer dashboard tokenization when possible; use this endpoint only for trusted agent flows that already have the user's card details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreCreditCardRequest'
            example:
              card_number: '4111111111111111'
              expiration: 12/2030
              cvc: '123'
              cardholder_name: Jane Doe
              email: jane@example.com
              billing_address:
                line1: 123 Market St
                city: San Francisco
                state: CA
                postal_code: '94105'
                country: US
              shipping_address:
                line1: 123 Market St
                city: San Francisco
                state: CA
                postal_code: '94105'
                country: US
                phone: '+14155550123'
      responses:
        '200':
          description: Successful response.
    get:
      operationId: getApiCreditCards
      tags:
      - Cards
      summary: List stored credit card payment methods
      description: List saved credit card payment methods for the agent, including the default payment method. Raw card numbers and CVCs are not returned.
      parameters:
      - name: agentId
        in: query
        required: false
        schema:
          type: string
        description: Required when not authenticating with an agent API key.
      responses:
        '200':
          description: Successful response.
  /api/agents/{id}/link-payment-methods/link:
    post:
      operationId: postApiAgentsIdLinkPaymentMethodsLink
      tags:
      - Cards
      summary: Connect or save a Link payment method
      description: Start Link setup, or save a selected Link payment method with contact and shipping data after the user completes Link.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkPaymentMethodRequest'
            example:
              clientName: Checkout
      responses:
        '200':
          description: Successful response.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Agent ID.
  /api/agents/{id}/link-payment-methods/credential:
    post:
      operationId: postApiAgentsIdLinkPaymentMethodsCredential
      tags:
      - Cards
      summary: Create a Link payment credential
      description: Generate a one-time card credential from a saved Link payment method for a specific merchant and amount.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkPaymentCredentialRequest'
            example:
              linkPaymentMethodId: lpm_123
              amount: '25.00'
              currency: USD
              merchantName: Example
              merchantUrl: https://example.com
      responses:
        '200':
          description: Successful response.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Agent ID.
  /api/cards:
    post:
      operationId: postApiCards
      tags:
      - Cards
      summary: Get a checkout card
      description: Fetch a usable checkout card from Sponge Card or a vaulted card source. If more than one card source is available, the API can return a selection response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCardRequest'
            example:
              card_type: sponge_card
              amount: '25.00'
              currency: USD
              merchant_name: Example
              merchant_url: https://example.com
      responses:
        '200':
          description: Successful response.
  /api/virtual-cards:
    post:
      operationId: postApiVirtualCards
      tags:
      - Cards
      summary: Issue a virtual card
      description: Issue a per-transaction virtual card for a specific merchant and amount.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueVirtualCardRequest'
            example:
              amount: '25.00'
              currency: USD
              merchant_name: Example
              merchant_url: https://example.com
      responses:
        '200':
          description: Successful response.
  /api/card-usage:
    post:
      operationId: postApiCardUsage
      tags:
      - Cards
      summary: Report card usage
      description: Report the outcome of a purchase attempt that used a stored or vaulted card.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportCardUsageRequest'
            example:
              payment_method_id: pm_123
              status: success
              amount: '25.00'
              currency: USD
              merchant_name: Example
      responses:
        '200':
          description: Successful response.
components:
  schemas:
    IssueVirtualCardRequest:
      type: object
      required:
      - amount
      - merchant_name
      - merchant_url
      properties:
        amount:
          type: string
        currency:
          type: string
          description: ISO 4217 currency code. Defaults to USD.
        merchant_name:
          type: string
        merchant_url:
          type: string
        merchant_country_code:
          type: string
        description:
          type: string
        products:
          type: array
          items:
            $ref: '#/components/schemas/ProductLineItem'
        shipping_address:
          $ref: '#/components/schemas/VirtualCardShippingAddress'
        enrollment_id:
          type: string
        agentId:
          type: string
          description: Required when not authenticating with an agent API key.
    StoreCreditCardRequest:
      type: object
      required:
      - card_number
      - cvc
      - cardholder_name
      - email
      - billing_address
      - shipping_address
      properties:
        card_number:
          type: string
          description: Card number.
        expiry_month:
          type: string
          description: Expiry month, used with expiry_year.
        expiry_year:
          type: string
          description: Expiry year, used with expiry_month.
        expiration:
          type: string
          description: Expiration in MM/YYYY format.
        cvc:
          type: string
          description: Card verification code.
        cardholder_name:
          type: string
        email:
          type: string
        billing_address:
          $ref: '#/components/schemas/CardBillingAddress'
        shipping_address:
          $ref: '#/components/schemas/CardShippingAddress'
        label:
          type: string
        metadata:
          type: object
          additionalProperties: true
        agentId:
          type: string
          description: Required when not authenticating with an agent API key.
    LinkPaymentCredentialRequest:
      type: object
      properties:
        linkPaymentMethodId:
          type: string
          description: Saved Sponge or Link payment method ID.
        spendRequestId:
          type: string
          description: Spend request ID returned by a previous approval_required response.
        amount:
          type: string
          description: Purchase amount, for example 49.99.
        currency:
          type: string
          description: ISO 4217 currency code. Defaults to USD.
        merchantName:
          type: string
        merchantUrl:
          type: string
        context:
          type: string
    LinkPaymentMethodRequest:
      type: object
      properties:
        linkPaymentMethodId:
          type: string
          description: Link payment method ID. Required when multiple methods are available.
        setAsDefault:
          type: boolean
        clientName:
          type: string
        email:
          type: string
          description: Required when saving the method.
        phone:
          type: string
          description: Required when saving the method.
        billing:
          $ref: '#/components/schemas/LinkAddress'
        shipping:
          $ref: '#/components/schemas/LinkAddress'
    VirtualCardShippingAddress:
      type: object
      required:
      - line1
      - city
      - state
      - postal_code
      - country_code
      properties:
        line1:
          type: string
        city:
          type: string
        state:
          type: string
        postal_code:
          type: string
        country_code:
          type: string
    CardShippingAddress:
      type: object
      required:
      - line1
      - city
      - state
      - postal_code
      - country
      - phone
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        state:
          type: string
        postal_code:
          type: string
        country:
          type: string
        phone:
          type: string
    CardBillingAddress:
      type: object
      required:
      - line1
      - city
      - state
      - postal_code
      - country
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        state:
          type: string
        postal_code:
          type: string
        country:
          type: string
    ReportCardUsageRequest:
      type: object
      required:
      - payment_method_id
      - status
      properties:
        payment_method_id:
          type: string
        merchant_name:
          type: string
        merchant_domain:
          type: string
        amount:
          type: string
        currency:
          type: string
        status:
          type: string
          enum:
          - success
          - failed
          - cancelled
        failure_reason:
          type: string
        agentId:
          type: string
          description: Required when not authenticating with an agent API key.
    GetCardRequest:
      type: object
      properties:
        card_type:
          type: string
          enum:
          - sponge_card
          - basis_theory_vaulted
        payment_method_id:
          type: string
        amount:
          type: string
        currency:
          type: string
        merchant_name:
          type: string
        merchant_url:
          type: string
        agentId:
          type: string
          description: Required when not authenticating with an agent API key.
    ProductLineItem:
      type: object
      required:
      - name
      - price
      - quantity
      properties:
        name:
          type: string
        price:
          type: number
        quantity:
          type: number
    LinkAddress:
      type: object
      required:
      - name
      - line1
      - city
      - state
      - postalCode
      - country
      properties:
        name:
          type: string
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
x-provenance:
  method: harvested
  publisher: Sponge
  source: https://mintlify-s3-bucket-3cc1a52.s3.us-east-1.amazonaws.com/32c2acfd-8ca8-4031-9e3a-874d50a5e93a?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIAULUIU2DMISKRXIWF%2F20261004%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261004T224040Z&X-Amz-Expires=3600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEAYaCXVzLWVhc3QtMSJGMEQCIAxh1KB13cnrN5mQ6KdF0vXJlMt%2BsDLGffr2ZeC82wZ6AiB3DPaK%2Fgp3u0%2FnMgy1eCdnCTpE5CBcOk4JDFilS3CSBiqWBAjP%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAEaDDI5OTg2MDU0NTc1MiIM0Q%2F5zI38GNThkDphKuoDjLwkHYJuD2A9%2BZ18egYgLCv2a33upid1uMZaq5yXqiruBdSCA%2FiAzXuFAPdkgBoocSIr18JHutWdDpZd3VnXBXzhv%2FraO9brQrk6E01I6jjpUg1MdxrcVvP%2BOLURs5%2B8zH303ymO6MANGjTWjOyQggA6ZDkzPehviQ8zLx%2FLFTI%2BntLRqBvE5huZsqlSxIrqFMP8tKMvONGC5uDhJobGIE76Fji9Kdldc%2BAzkXQWg02Ftd%2BK4pssd4sY34VCuJfayXVk4KakSPabOF1iQhhkqVcc8BmzP3JWPwhIHsG0VYeagCUe49ogoW4Yn%2Fji0rngSYMsgqHK5VwbUQG46mzXTQPLJs4HYO2yhQ6u8yxF6lW7B3kMKTe6xTL3cbigW0eKytHl8lBg7CsOfrp1mXdcli59YArljrZHLSqC2xxmy%2Frx%2BQey%2BQM685nYvFu9p7w%2BCsKBjNqrksjoEqH0JZ1Bd%2BcLgeYwRw3BNH6X0aMu8T0e%2BNITs%2BXTTo3YKMOXdA6jFELTmKWHRZ5pDMNfSBBpa8vuK6wtL9CaNoFHXEHn5SEH91LtjTOUPusCQ8xuitdsg1b1xnO7EY04FldIs1UeqxAx0tJvMEMmFKJbAC1R9B%2FjZIYtIvsaVhRENxhIAjVqkCffU5IAi5huoTDElovWBjqmAenN7dM0J8DxfARdQu%2FKETJxR8FGPsIJAR69ugn9utc0wRC8XcYSTbLZZO1eO41bf03k5tur0xKNwaneY1yUmSKwima%2BL3JXnyGcX0hg7X%2FfNLaK8KM10xLqPKQnoixOWxaRfNHrXpGRMfsSxW17a8Tr1ahU7D9mjmBONKhzEJKrUjmMq%2FGMCAibb%2BctKaCxSf643lydRdztwaPTVoLOFWx6IVu%2BAPM%3D&X-Amz-Signature=bc63f16f7d81150e27d1128acdad2bcee87003d1bd63bd922f4d3d49b03c4acc&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)