Weav Docsv1
Back to homeSupportGet API keys

API reference / Payment methods

Save a payment method

View as Markdown
More actions
Open in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in GrokAsk questions about this pageConnect to CursorInstall the MCP server in CursorConnect to VS CodeInstall the MCP server in VS Code
POST/v1/payment-methods

Saves a customer's card for later charges with no payer present (auto-debit, subscriptions). Send your customer to next_action.checkout_url: Weav's save page, where they type their card, agree to future charges and confirm it with their bank (3DS). Their bank may show a ₱10.00 check that is canceled right after. The card goes from their browser to the card processor; it never reaches Weav or you.

You get PAYMENT_METHOD_SAVED (now ACTIVE: charge it with POST /v1/payments and its payment_method_id) or PAYMENT_METHOD_FAILED. A link not used within 24 hours fails. Only cards today (type: CARD).

Saving cards is off until Weav turns it on for your account with your PCI DSS evidence (422 4220401); in test mode it always works, with a test save page.

Headers

  • AuthorizationstringRequired
    Bearer plus your API key. See Authentication.

Body

JSON, with Content-Type: application/json.

  • typestringRequired
    One of: CARD
  • customerobjectRequired
    3 fields in customer
    • idstringRequired
      Your own ID for the customer. List their saved methods with it.
      Up to 64 charactersPattern: ^[A-Za-z0-9._:@-]+$
    • namestring | null
      Weav's save page asks your customer when you leave it out.
      Up to 255 characters
    • emailstring (email) | null
      Up to 255 characters
  • success_urlstring (uri) | null
    HTTPS. Where your customer goes once it's saved.
    Up to 2048 characters
  • cancel_urlstring (uri) | null
    HTTPS. Where your customer goes if they leave, or the bank's check fails.
    Up to 2048 characters
  • webhook_urlstring | null
    This payment method's webhooks go here instead of your webhook URL.
    Up to 2048 characters

Responses

201 Created

Payment method created (code 2010400).

What data holds
  • payment_methodobject
    16 fields in payment_method
    • idstring
    • typestring
      One of: CARD
    • statusstring
      PENDING until your customer saves it and their bank confirms it; ACTIVE (chargeable); FAILED when that never happens; REMOVED.
      One of: PENDING ACTIVE FAILED REMOVED
    • customerobject
      3 fields in customer
      • idstring
      • namestring | null
      • emailstring | null
    • cardobject | null
      Once saved. Never the card number.
      4 fields in card
      • brandstring
        From the card processor.
        One of: VISA MASTERCARD JCB
      • last4string
      • exp_monthinteger | null
        The expiry month your customer typed. Ask them for a new card before it passes (expires_by on the list).
        At least 1At most 12
      • exp_yearinteger | null
        Four digits.
    • labelstring | null
      To show your customer.
    • next_actionobject
      2 fields in next_action
      • typestring | null
        One of: REDIRECT
      • checkout_urlstring (uri) | null
        Weav's save page, while PENDING.
    • success_urlstring (uri) | null
    • cancel_urlstring (uri) | null
    • webhook_urlstring | null
    • expires_atstring (date-time) | null
      When the save link ends, while PENDING.
    • activated_atstring (date-time) | null
    • failed_atstring (date-time) | null
    • removed_atstring (date-time) | null
    • created_atstring (date-time)
    • updated_atstring (date-time)

401 Unauthorized

Missing, malformed or unknown API key (code 4010000).

403 Forbidden

The key can't make this request (code 4030000): an address outside the key's IP allowlist, a live key before your live mode is on, or an account that isn't active. A live key sent from a browser is refused (code 4030001): keep live keys on your server.

422 Unprocessable Content

Invalid fields, or saving cards is off for your account (4220401).

POST

Try it: Save a payment method

Test mode
Authorization
Body
Valid JSON
cURL
Uses $WEAV_API_KEY, never your key. Paste it into a terminal, or import it into Postman.
Response
Send the request to see Weav's answer here.
curl -X POST https://api.weavpayments.com/v1/payment-methods \
    -H "Authorization: Bearer $WEAV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "type": "CARD",
    "customer": {
        "id": "USER-123",
        "name": "Juan dela Cruz",
        "email": "juan@example.com"
    },
    "success_url": "https://shop.example/account/cards",
    "cancel_url": "https://shop.example/account"
}'
{
    "code": "2010400",
    "success": true,
    "message": "Payment method created",
    "data": {
        "payment_method": {
            "id": "PM8K2Q7X9KBAT4MZ3N",
            "type": "CARD",
            "status": "PENDING",
            "customer": {
                "id": "USER-123",
                "name": "Juan dela Cruz",
                "email": "juan@example.com"
            },
            "card": null,
            "label": null,
            "next_action": {
                "type": "REDIRECT",
                "checkout_url": "https://pay.weavpayments.com/save/PM8K2Q7X9KBAT4MZ3N"
            },
            "success_url": "https://shop.example/account/cards",
            "cancel_url": "https://shop.example/account",
            "webhook_url": null,
            "expires_at": "2026-11-03T10:12:00+08:00",
            "activated_at": null,
            "failed_at": null,
            "removed_at": null,
            "created_at": "2026-11-02T10:12:00+08:00",
            "updated_at": "2026-11-02T10:12:00+08:00"
        }
    }
}