{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab","admonition"]},"type":"markdown"},"seo":{"title":"Reefpay Docs","description":"Reefpay is the groundbreaking payment gateway that lets you integrate with the future of payments.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"store-a-card-for-future-use","__idx":0},"children":["Store a card for future use"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A valid API key — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/how-tos/setup/obtain-credentials"},"children":["Obtain API credentials"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The person's card details (PAN, expiry, cardholder name) and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer_id"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-build-the-request","__idx":2},"children":["Step 1: Build the request"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Your internal customer identifier"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_default"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," to make this the customer's default card"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nickname"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A friendly label (for example, \"Personal Visa\")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card.pan"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Full card number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card.expiry_month"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Two-digit expiry month"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card.expiry_year"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Four-digit expiry year"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card.cardholder_name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Name on card"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card.address.line1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Recommended"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Billing street address (for AVS verification at tokenization)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card.address.zip"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Recommended"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Billing ZIP code"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-send-the-request","__idx":3},"children":["Step 2: Send the request"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X POST \\\n  https://api.dev.paradisegateway.net/v1/payment_tokens \\\n  -H \"Content-Type: application/json\" \\\n  -H \"APIKEY: YOUR-API-KEY\" \\\n  -d '{\n    \"customer_id\": \"CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB\",\n    \"is_default\": true,\n    \"nickname\": \"My Business Visa\",\n    \"card\": {\n      \"pan\": \"4111111111111111\",\n      \"expiry_month\": \"12\",\n      \"expiry_year\": \"2027\",\n      \"cardholder_name\": \"John A Doe\",\n      \"address\": {\n        \"line1\": \"123 Main St\",\n        \"zip\": \"62704\"\n      }\n    }\n  }'\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests\n\nresp = requests.post(\n    \"https://api.dev.paradisegateway.net/v1/payment_tokens\",\n    headers={\"Content-Type\": \"application/json\", \"APIKEY\": \"YOUR-API-KEY\"},\n    json={\n        \"customer_id\": \"CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB\",\n        \"is_default\": True,\n        \"nickname\": \"My Business Visa\",\n        \"card\": {\n            \"pan\": \"4111111111111111\",\n            \"expiry_month\": \"12\",\n            \"expiry_year\": \"2027\",\n            \"cardholder_name\": \"John A Doe\",\n            \"address\": {\"line1\": \"123 Main St\", \"zip\": \"62704\"},\n        },\n    },\n)\nprint(resp.json())\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const resp = await fetch(\n  \"https://api.dev.paradisegateway.net/v1/payment_tokens\",\n  {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      \"APIKEY\": \"YOUR-API-KEY\",\n    },\n    body: JSON.stringify({\n      customer_id: \"CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB\",\n      is_default: true,\n      nickname: \"My Business Visa\",\n      card: {\n        pan: \"4111111111111111\",\n        expiry_month: \"12\",\n        expiry_year: \"2027\",\n        cardholder_name: \"John A Doe\",\n        address: { line1: \"123 Main St\", zip: \"62704\" },\n      },\n    }),\n  }\n);\nconsole.log(await resp.json());\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csharp","header":{"controls":{"copy":{}}},"source":"using var client = new HttpClient();\nclient.DefaultRequestHeaders.Add(\"APIKEY\", \"YOUR-API-KEY\");\n\nvar payload = new\n{\n    customer_id = \"CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB\",\n    is_default = true,\n    nickname = \"My Business Visa\",\n    card = new\n    {\n        pan = \"4111111111111111\",\n        expiry_month = \"12\",\n        expiry_year = \"2027\",\n        cardholder_name = \"John A Doe\",\n        address = new { line1 = \"123 Main St\", zip = \"62704\" }\n    }\n};\nvar resp = await client.PostAsJsonAsync(\n    \"https://api.dev.paradisegateway.net/v1/payment_tokens\", payload);\nConsole.WriteLine(await resp.Content.ReadAsStringAsync());\n","lang":"csharp"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Java","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"HttpClient client = HttpClient.newHttpClient();\nString body = \"\"\"\n    {\n      \"customer_id\": \"CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB\",\n      \"is_default\": true,\n      \"nickname\": \"My Business Visa\",\n      \"card\": {\n        \"pan\": \"4111111111111111\",\n        \"expiry_month\": \"12\",\n        \"expiry_year\": \"2027\",\n        \"cardholder_name\": \"John A Doe\",\n        \"address\": { \"line1\": \"123 Main St\", \"zip\": \"62704\" }\n      }\n    }\n    \"\"\";\nHttpRequest request = HttpRequest.newBuilder()\n    .uri(URI.create(\"https://api.dev.paradisegateway.net/v1/payment_tokens\"))\n    .header(\"Content-Type\", \"application/json\")\n    .header(\"APIKEY\", \"YOUR-API-KEY\")\n    .POST(HttpRequest.BodyPublishers.ofString(body)).build();\nHttpResponse<String> resp = client.send(request,\n    HttpResponse.BodyHandlers.ofString());\nSystem.out.println(resp.body());\n","lang":"java"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Go","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"go","header":{"controls":{"copy":{}}},"source":"payload := strings.NewReader(`{\n  \"customer_id\": \"CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB\",\n  \"is_default\": true,\n  \"nickname\": \"My Business Visa\",\n  \"card\": {\n    \"pan\": \"4111111111111111\",\n    \"expiry_month\": \"12\",\n    \"expiry_year\": \"2027\",\n    \"cardholder_name\": \"John A Doe\",\n    \"address\": { \"line1\": \"123 Main St\", \"zip\": \"62704\" }\n  }\n}`)\nreq, _ := http.NewRequest(\"POST\",\n    \"https://api.dev.paradisegateway.net/v1/payment_tokens\", payload)\nreq.Header.Set(\"Content-Type\", \"application/json\")\nreq.Header.Set(\"APIKEY\", \"YOUR-API-KEY\")\nresp, _ := http.DefaultClient.Do(req)\ndefer resp.Body.Close()\nbody, _ := io.ReadAll(resp.Body)\nfmt.Println(string(body))\n","lang":"go"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"PHP","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"php","header":{"controls":{"copy":{}}},"source":"$ch = curl_init(\"https://api.dev.paradisegateway.net/v1/payment_tokens\");\ncurl_setopt_array($ch, [\n    CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,\n    CURLOPT_HTTPHEADER => [\"Content-Type: application/json\", \"APIKEY: YOUR-API-KEY\"],\n    CURLOPT_POSTFIELDS => json_encode([\n        \"customer_id\" => \"CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB\",\n        \"is_default\" => true,\n        \"nickname\" => \"My Business Visa\",\n        \"card\" => [\n            \"pan\" => \"4111111111111111\",\n            \"expiry_month\" => \"12\", \"expiry_year\" => \"2027\",\n            \"cardholder_name\" => \"John A Doe\",\n            \"address\" => [\"line1\" => \"123 Main St\", \"zip\" => \"62704\"],\n        ],\n    ]),\n]);\necho curl_exec($ch); curl_close($ch);\n","lang":"php"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Ruby","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"require \"net/http\"; require \"json\"\nuri = URI(\"https://api.dev.paradisegateway.net/v1/payment_tokens\")\nreq = Net::HTTP::Post.new(uri, {\n  \"Content-Type\" => \"application/json\", \"APIKEY\" => \"YOUR-API-KEY\",\n})\nreq.body = {\n  customer_id: \"CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB\",\n  is_default: true, nickname: \"My Business Visa\",\n  card: {\n    pan: \"4111111111111111\", expiry_month: \"12\", expiry_year: \"2027\",\n    cardholder_name: \"John A Doe\",\n    address: { line1: \"123 Main St\", zip: \"62704\" },\n  },\n}.to_json\nresp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }\nputs resp.body\n","lang":"ruby"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-handle-the-response","__idx":4},"children":["Step 3: Handle the response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}," response returns the token and masked card details."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"payment_token\": \"PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB\",\n  \"object\": \"payment_token\",\n  \"type\": \"card\",\n  \"status\": \"active\",\n  \"customer_id\": \"CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB\",\n  \"is_default\": true,\n  \"nickname\": \"My Business Visa\",\n  \"card\": {\n    \"brand\": \"visa\",\n    \"last_four\": \"1111\",\n    \"bin\": \"411111\",\n    \"funding\": \"credit\",\n    \"address_check\": {\n      \"address_line1_match\": \"match\",\n      \"address_zip_match\": \"match\"\n    }\n  },\n  \"correlation_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_token"]}," value. Use it in future transactions with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_method.type: payment_token"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"AVS at tokenization"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you provide address data, Paradise Gateway verifies it with the card issuer at tokenization time. Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address_check"]}," results to confirm the address matches before using the token."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-responses","__idx":5},"children":["Error responses"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid request (missing required fields)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Validation failed (invalid card number, expired card)"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":6},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/how-tos/process-payments/process-payment-with-token"},"children":["Process a payment with a stored token"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/how-tos/tokenization-vaulting/update-payment-method"},"children":["Update stored payment method"]}," — change expiry or nickname"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/tokenization/what-is-tokenization"},"children":["About tokenization"]}]}]}]},"headings":[{"value":"Store a card for future use","id":"store-a-card-for-future-use","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Build the request","id":"step-1-build-the-request","depth":2},{"value":"Step 2: Send the request","id":"step-2-send-the-request","depth":2},{"value":"Step 3: Handle the response","id":"step-3-handle-the-response","depth":2},{"value":"Error responses","id":"error-responses","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Store a card for future use","shortTitle":"Store a card","intro":"Tokenize a credit or debit card through the Payment Tokens API. The card is encrypted and stored in the PCI-compliant vault, and you receive a reusable payment_token.","type":"how-to","seo":{"title":""}},"lastModified":"2026-06-05T02:46:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/how-tos/tokenization-vaulting/store-card","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}