### Build and start the project Source: https://safepay-docs.netlify.app/documentation/run-locally Build the Next.js application and start the development server. ```bash # Assuming you are in the project directory # Build the project npm run build # Start the project npm start ``` -------------------------------- ### Install dependencies Source: https://safepay-docs.netlify.app/documentation/run-locally Install all required project dependencies using npm. ```bash # Install the dependencies npm i ``` -------------------------------- ### Install Safepay Atoms via npm Source: https://safepay-docs.netlify.app/build-your-integration/advanced-checkout/safepay-atoms Run this command in your project root to install the Atoms library. ```bash npm install @sfpy/atoms ``` -------------------------------- ### Authorization Response Example Source: https://safepay-docs.netlify.app/build-your-integration/advanced-checkout/cardinal Example response received after executing an authorization action. ```json { "authorization_status": "authorized", "transaction_id": "txn_67890" } ``` -------------------------------- ### Install Node.js API library Source: https://safepay-docs.netlify.app/build-your-integration/advanced-checkout/introduction Commands to install or update the official Safepay Node.js core library using npm. ```bash # Install the API library npm install --save @sfpy/node-core # Update the API library npm update @sfpy/node-core ``` -------------------------------- ### Example Return URL Source: https://safepay-docs.netlify.app/build-your-integration/express-checkout The URL structure containing the tracker token appended after a shopper completes a payment. ```text https://your-company.com/order/complete?tracker=track_4f7d7e2d-ee05-44e3-81b7-6f6f2cca9727 ``` -------------------------------- ### Rendered Output Example Source: https://safepay-docs.netlify.app/components/Text/Pre Visual representation of the output generated by the PRE component. ```text function hello() { console.log("Hello, world!") } ``` -------------------------------- ### Customer Creation Response Example Source: https://safepay-docs.netlify.app/build-your-integration/express-checkout?platform-=react-native The JSON response structure returned after successfully creating a customer, containing the required token. ```json { "data": { "token": "cus_e927d58d-3796-4f36-a209-384906d712ea", "merchant_api_key": "sec_edeade52-46aa-483b-b87d-009d3ce41554", "email": "hzaidi@getsafepay.com", "first_name": "Hassan", "last_name": "Zaidi", "phone_number": "+923331234567", "country": "PK", "is_guest": true, "is_deleted": false, "created_at": { "seconds": 1697986036, "nanos": 25310172 }, "updated_at": { "seconds": 1697986036, "nanos": 25310589 } }, "status": { "errors": [], "message": "success" } } ``` -------------------------------- ### Start StepUpFlow with continueWithTransactionId Source: https://safepay-docs.netlify.app/build-your-integration/advanced-checkout/cardinal Initiate the StepUpFlow by calling continueWithTransactionId in Objective-C or Swift. ```objective-c payload:@"[PAYLOAD]" didValidateDelegate:self]; ``` ```swift session.continueWith(transactionId: "[TRANSACTION_ID]", payload: "[PAYLOAD]", validationDelegate: self) ``` -------------------------------- ### Tracker next_actions configuration Source: https://safepay-docs.netlify.app/concepts/payment-actions Example of a tracker object specifying the next action required for a Cybersource payment. ```json { "intent": "CYBERSOURCE", "mode": "payment", "next_actions": { "CYBERSOURCE": { "kind": "GENERATE_CAPTURE_CONTEXT" } } } ``` -------------------------------- ### Client token response format Source: https://safepay-docs.netlify.app/build-your-integration/advanced-checkout/introduction Example JSON response received after requesting a client authentication token. ```json { "data": "xnTyRgITVcHlyeKT2cf59_e836PouieQ6xPpuQiwFXD8M6HoJ283EP_zta2SKkm6B_IFNGEBmg==" } ``` -------------------------------- ### subscription.payment.succeeded webhook payload Source: https://safepay-docs.netlify.app/developers/webhooks/webhook-types Example JSON payload for a successful subscription payment. ```json { "token":"evt_ea9ab1a2-4a3b-478a-ac82-cb986b60242e", "version":"2.0.0", "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554", "type":"subscription.payment.succeeded", "endpoint":"http://example.com", "data":{ "id":"sub_73f6b269-4c8e-44d6-b55e-b982ef5f2835", "plan_id":"plan_c749c21e-f075-4cc4-8d3d-4e44e6bf3623", "customer_email":"hzaidi@getsafepay.com", "status":"ACTIVE", "billing_cycle_anchor":{ "seconds":1698758633 }, "amount":100000, "currency":"PKR", "balance":"0", "current_period_start_date":{ "seconds":1698758633 }, "current_period_end_date":{ "seconds":1698758692 }, "last_paid_date":{ "seconds":1698758586, "nanos":667158380 }, "current_billing_cycle":1, "updated_at":{ "seconds":1698758573 }, "created_at":{ "seconds":1698758573 }, "transaction_id":"txn_8b29b706-168d-4b38-991c-ac77620a29b7", "transaction_status":"COMPLETE" }, "created_at":{ "seconds":1698758586, "nanos":858671671 } } ``` -------------------------------- ### Handle Authentication Callbacks Source: https://safepay-docs.netlify.app/build-your-integration/advanced-checkout/safepay-react Example JSON structures emitted by the component callbacks to monitor authentication events. ```json { "detail": { "payment_method": null, "request_id": "req_23461744-c342-42ef-9bed-f54f709c40d9", "tracker": "track_a098c800-a24b-4eb2-ab62-aa8967a099df" }, "name": "safepay-inframe__cardinal-3ds__success", "type": "safepay-inframe-event" } ``` ```json { "detail": { "error": "error performing action 'PAYER_AUTH_ENROLLMENT': Encountered an error while performing payer authentication: payer could not be authenticated. Please try again with a different card or another form of payment.", "request_id": null, "tracker": "track_03ca9dca-3ee5-40fe-95e3-931554d0ef16" }, "name": "safepay-inframe__cardinal-3ds__failure", "type": "safepay-inframe-event" } ``` ```json { "detail": { "request_id": "req_b15699bd-415e-4ed3-866b-227bbe69f714", "tracker": "track_c6ead7f5-681c-469e-ab9f-4f2cc1f144e8" }, "name": "safepay-inframe__enrollment__frictionless", "type": "safepay-inframe-event" } ``` ```json { "detail": { "errorMessage": "error performing action 'PAYER_AUTH_ENROLLMENT': Encountered an error while performing payer authentication: payer could not be authenticated. Please try again with a different card or another form of payment." }, "name": "safepay-inframe__enrollment__failed", "type": "safepay-inframe-event" } ``` ```json { "detail": { "error": { "status": 400, "type": "SafepayAPIError" } }, "name": "safepay-error", "type": "safepay-inframe-event" } ``` -------------------------------- ### Perform Payer Authentication Setup Source: https://safepay-docs.netlify.app/developers/payment-journeys/customer Initiate the payer authentication process by sending payment method details to the tracker endpoint. ```cURL curl --location 'https://sandbox.api.getsafepay.com/order/payments/v3/track_dccdef16-008e-4fae-81cc-1b7d81bf6c44' \ --data '{ "payload": { "payment_method": { "card": { "card_number": "5200000000001096", "expiration_month": "12", "expiration_year": "2028", "cvv": "123" } } } }' ``` -------------------------------- ### Instrument mode response example Source: https://safepay-docs.netlify.app/concepts/tokenization/implementation The API returns a tracker object containing the token and next actions required for authentication. ```json { "data": { "tracker": { "token": "track_e244f1fa-4af4-4dc4-8d6f-8101b36bedf6", "client": "sec_a7cc6fc1-088d-4f35-9dac-2bab2cb234a1", "environment": "sandbox", "state": "TRACKER_STARTED", "intent": "CYBERSOURCE", "mode": "instrument", "entry_mode": "raw", "customer": "cus_b4afd638-41bf-4831-af07-587b51269f38", "next_actions": { "CYBERSOURCE": { "kind": "PAYER_AUTH_SETUP" }, "MPGS": { "kind": "NOOP" } }, "purchase_totals": { "quote_amount": { "currency": "PKR", "amount": 500 }, "base_amount": { "currency": "PKR", "amount": 500 }, "conversion_rate": { "base_currency": "PKR", "quote_currency": "PKR", "rate": 1 } }, "metadata": {} }, "capabilities": { "CYBERSOURCE": true, "MPGS": true } }, "status": { "errors": [], "message": "success" } } ``` -------------------------------- ### Clone and navigate to the project Source: https://safepay-docs.netlify.app/documentation/run-locally Use these commands to download the repository and enter the project directory. ```bash # Clone the safepay-docs repo git clone git@github.com:getsafepay/safepay-docs.git # Navigate to the project directory cd safepay-docs ``` -------------------------------- ### Basic FileTree Implementation Source: https://safepay-docs.netlify.app/components/FileTree Demonstrates how to import and use the FileTree component with a mix of simple file paths and path-note tuples. ```jsx import React from 'react'; import { FileTree } from '~/ui/components/FileTree'; const files = [ "index.js", ["src/App.js", "Main application file"], "src/components/Button.js", ["src/layouts/MainLayout.js", "Includes sidebar and navbar"] ]; export default function App() { return (

Project Files

); } ``` -------------------------------- ### Initialize a new Safepay project Source: https://safepay-docs.netlify.app/ Use the CLI command to scaffold a new Safepay application environment. ```bash npx init my-safepay-app ``` -------------------------------- ### Basic Step Component Usage Source: https://safepay-docs.netlify.app/components/Step Demonstrates how to import and implement the Step component to create a sequence of steps. ```jsx import React from 'react'; import { Step } from '~/ui/components/Step'; export default function App() { return (
This is the first step of the process Here's what you need to do for the second step.
); } ``` -------------------------------- ### subscription.resumed webhook payload Source: https://safepay-docs.netlify.app/developers/webhooks/webhook-types Example JSON payload for a subscription that has been resumed. ```json { "token":"evt_9e0c9f81-8607-4fd7-936c-56fed465ee90", "version":"2.0.0", "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554", "type":"subscription.resumed", "endpoint":"http://example.com", "data":{ "id":"sub_5726bec7-1d2a-424d-a650-04b963c0e854", "plan_id":"plan_c749c21e-f075-4cc4-8d3d-4e44e6bf3623", "customer_email":"hzaidi@getsafepay.com", "status":"ACTIVE", "billing_cycle_anchor":{ "seconds":1698760196 }, "amount":100000, "currency":"PKR", "balance":"0", "resumed_at":{ "seconds":1698760196 }, "updated_at":{ "seconds":1698760196 }, "created_at":{ "seconds":1698760185 } }, "created_at":{ "seconds":1698760196, "nanos":518876958 } } ``` -------------------------------- ### safepay.payments.session.setup Source: https://safepay-docs.netlify.app/build-your-integration/advanced-checkout/introduction Initializes a payment session by creating a tracker with transaction details. ```APIDOC ## SDK Method: safepay.payments.session.setup ### Description Creates a payment session (Tracker) to prepare for a transaction. This should be called before the customer initiates the payment. ### Parameters - **merchant_api_key** (string) - Required - Your merchant API key. - **user** (string) - Optional - The ID of the merchant shopper. - **intent** (string) - Required - The payment intent (e.g., CYBERSOURCE). - **mode** (string) - Required - The mode of operation (e.g., payment). - **entry_mode** (string) - Required - The entry mode (e.g., raw). - **currency** (string) - Required - The currency code (e.g., USD). - **amount** (number) - Required - The transaction amount in minor units. - **metadata** (object) - Optional - Additional information such as order_id. ``` -------------------------------- ### subscription.paused webhook payload Source: https://safepay-docs.netlify.app/developers/webhooks/webhook-types Example JSON payload for a subscription that has been paused. ```json { "token":"evt_3ebf1fea-b065-4a7d-925c-199245f98114", "version":"2.0.0", "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554", "type":"subscription.paused", "endpoint":"http://example.com", "data":{ "id":"sub_7e48edb7-daf8-47bf-9679-5b1cf24ff614", "plan_id":"plan_22933989-a533-44d6-80d2-c1816571f451", "customer_email":"hzaidi@getsafepay.com", "status":"PAUSED", "billing_cycle_anchor":{ "seconds":1698760037 }, "amount":300000, "currency":"PKR", "balance":"0", "paused_at":{ "seconds":1698760042 }, "updated_at":{ "seconds":1698760042 }, "created_at":{ "seconds":1698760037 } }, "created_at":{ "seconds":1698760042, "nanos":438161220 } } ``` -------------------------------- ### Location Object Structure Source: https://safepay-docs.netlify.app/concepts/tracker Example of the location data associated with a tracker. ```json "location":{ "tracker":"track_e772f8b3-edc7-4a6f-9e85-94d262c03087", "token":"loc_4839390b-2f1e-4a24-a079-eb512ceb21db", "ip_address":"203.130.3.66", "city":"Karachi", "country":"PK", "latitude":24.883, "longitude":67.058, "region":"Sindh", "created_at":{ "seconds":1723194410 }, "updated_at":{ "seconds":1723194410 } } ``` -------------------------------- ### Create a new tracker Source: https://safepay-docs.netlify.app/developers/tokenization/customer Initiate a setupPayment request to associate a customer with a tracker for saving payment methods. Set mode to 'instrument' to specifically save a payment method. ```cURL // For live payments use https://api.getsafepay.com curl --location 'https://sandbox.api.getsafepay.com/order/payments/v3/' \ --data '{ "merchant_api_key": "sec_ed8fa26a-e36d-49d2-89bd-1c72c8b5c133", "user" : "cus_e927d58d-3796-4f36-a209-384906d712ea", "intent": "CYBERSOURCE", "mode": "instrument", "is_account_verification": true, "currency": "PKR", }' ``` -------------------------------- ### subscription.payment.failed webhook payload Source: https://safepay-docs.netlify.app/developers/webhooks/webhook-types Example JSON payload for a failed subscription payment. ```json { "token": "evt_3f8ee089-c083-4475-af48-036b38140053", "version": "2.0.0", "merchant_api_key": "sec_d2ec84f8-eae4-4e50-80ba-dad01c7bab83", "type": "subscription.payment.failed", "endpoint": "https://example.com", "data": { "id": "sub_b55072cf-2556-4c17-82b4-dae075960df8", "plan_id": "plan_8ae8e989-08fd-47dd-9a95-04056c83b6fa", "customer_email": "hzaidi@getsafepay.com", "status": "UNPAID", "billing_cycle_anchor": { "seconds": 1710824626 }, "amount": 405100, "currency": "PKR", "balance": "0", "updated_at": { "seconds": 1710824626 }, "created_at": { "seconds": 1710824626 }, "transaction_id": "txn_b54bb42c-bc55-481b-b1d9-fd945f44f8c3", "transaction_status": "FAILED", "transaction_error_code": "NONE_TRANSACTION_FAILURE_CODE", "transaction_error_message": "unrecognized or unsupported action kind" }, "created_at": { "seconds": 1710825617, "nanos": 655468013 } } ``` -------------------------------- ### Implement a basic Button component in React Source: https://safepay-docs.netlify.app/components/Button Demonstrates importing the Button component and configuring its size, theme, and click handler. ```javascript import React, { useEffect } from 'react'; import { Button } from '@sfpy/styleguide' export default function App() { return (

Button Example

); } ``` -------------------------------- ### payment.refunded webhook payload Source: https://safepay-docs.netlify.app/developers/webhooks/webhook-types Example JSON payload for a processed refund event. ```json { "token":"evt_48431483-2111-4328-8729-309c96c7a0f6", "version":"2.0.0", "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554", "type":"payment.refunded", "endpoint":"http://example.com", "data":{ "tracker":"track_06ee38cb-981d-4158-819f-7231f28314e4", "intent":"CYBERSOURCE", "state":"TRACKER_PARTIAL_REFUND", "customer_email":"hzee@gmail.com", "balance":44000, "currency":"PKR", "metadata":{ "order_id":"AX-09u812312", "source":"shopify" }, "refund_amount":1000, "refunded_at":{ "seconds":1698758038, "nanos":682810001 } }, "created_at":{ "seconds":1698758038, "nanos":880931084 } } ``` -------------------------------- ### Create a Customer via Node.js Source: https://safepay-docs.netlify.app/build-your-integration/express-checkout?platform-=react-native Initializes the Safepay client and creates a customer record to pre-fill checkout details. ```javascript const safepay = require('@sfpy/node-core')('SAFEPAY_SECRET_KEY', { authType: 'secret', host: 'https://sandbox.api.getsafepay.com' }); (async () => { try { const response = await safepay.user.customers.create({ payload: { first_name: "Hassan", last_name: "Zaidi", email: "hzaidi@getsafepay.com", phone_number: "+923331234567", country: "PK", is_guest: true } }); console.log(response); } catch (error) { console.error(error); } })(); ``` -------------------------------- ### Create a subscription plan with Node.js Source: https://safepay-docs.netlify.app/developers/subscriptions/introduction Use the @sfpy/node-core SDK to define a recurring billing plan with specified amount, currency, and interval. ```javascript const safepay = require('@sfpy/node-core')({ api_key: 'YOUR_SERVER_API_KEY', authType: 'jwt', host: 'https://sandbox.api.getsafepay.com' }); (async () => { try { const response = await safepay.client.plans.create({ payload: { amount: "100", currency: "PKR", interval: "MONTH", type: "RECURRING", interval_count: 1, product: "bananas", active: true } }); console.log(response); } catch (error) { console.error(error); } })(); ``` -------------------------------- ### authorization.succeeded webhook payload Source: https://safepay-docs.netlify.app/developers/webhooks/webhook-types Example JSON payload for a successful card authorization event. ```json { "token": "evt_191b441e-a6f2-4d00-8bf3-01f8d5934fdp", "version": "2.0.0", "merchant_api_key": "sec_ed8fa26a-e36d-49d2-89bd-1c72c8b5c133", "type": "authorization.succeeded", "endpoint": "http://example.com", "data": { "amount": 45000, "authorization": "auth_9e3bb43e-3b54-44ad-a356-763677fa1d58", "authorized_at": { "nanos": 909405555, "seconds": 1738066360 }, "currency": "PKR", "customer_email": "test-notifications@getsafepay.com", "intent": "CYBERSOURCE", "metadata": { "order_id": "AX-09u812312", "source": "shopify" }, "state": "TRACKER_AUTHORIZED", "tracker": "track_06ee38cb-981d-4158-819f-7231f28314e4" }, "created_at": { "seconds": 1738066360, "nanos": 909416680 } } ``` -------------------------------- ### payment.succeeded webhook payload Source: https://safepay-docs.netlify.app/developers/webhooks/webhook-types Example JSON payload for a successful payment capture event. ```json { "token":"evt_64b3218e-f65c-45a9-96b0-fe4e293bb879", "version":"2.0.0", "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554", "type":"payment.succeeded", "endpoint":"http://example.com", "data":{ "tracker":"track_06ee38cb-981d-4158-819f-7231f28314e4", "intent":"CYBERSOURCE", "state":"TRACKER_ENDED", "net":43525, "fee":1475, "customer_email":"hzee@gmail.com", "amount":45000, "currency":"PKR", "metadata":{ "order_id":"AX-09u812312", "source":"shopify" }, "charged_at":{ "seconds":1698754230, "nanos":752997627 } }, "created_at":{ "seconds":1698754230, "nanos":912705711 } } ``` -------------------------------- ### Payment method response structure Source: https://safepay-docs.netlify.app/concepts/tokenization/manage-tokens Example JSON response returned by the findPaymentMethod endpoint. ```json { "data": { "token": "pm_bea00774-22ba-44ce-82c5-3cdd1a342e89", "customer": "cus_2fc20245-e0f8-447f-af75-fa651cfd54aa", "merchant_api_key": "sec_edeade52-46aa-483b-b87d-009d3ce41554", "kind": 1, "max_usage": 1, "usage_interval": 0, "is_deleted": false, "cybersource": { "token": "tms_b8543301-95ad-4eae-a86f-8d90a5ece0c7", "customer_payment_method": "pm_bea00774-22ba-44ce-82c5-3cdd1a342e89", "scheme": 2, "bin": "520000", "last_four": "1096", "expiry_month": "12", "expiry_year": "2023", "created_at": { "seconds": 1697697321 }, "updated_at": { "seconds": 1697697321 } }, "usage_count": 0, "expires_at": { "seconds": 1697783722 }, "created_at": { "seconds": 1697697321 }, "updated_at": { "seconds": 1697697321 } }, "status": { "errors": [], "message": "success" } } ``` -------------------------------- ### Create a payment session in Node.js Source: https://safepay-docs.netlify.app/build-your-integration/express-checkout Use the @sfpy/node-core package to initialize a session with your API key and payment details. ```javascript const safepay = require('@sfpy/node-core')('SAFEPAY_SECRET_KEY', { authType: 'secret', host: 'https://sandbox.api.getsafepay.com' // for live payments use https://api.getsafepay.com }); try { const response = safepay.payments.session.setup({ "merchant_api_key": "SAFEPAY_API_KEY", "intent": "CYBERSOURCE", "mode": "payment", "entry_mode": "raw", "currency": "USD", "amount": 10000, "metadata": { "order_id": "1234567890" }, "include_fees": false }) } catch (err) { console.log(error); } ``` -------------------------------- ### Webhook Event Payloads Source: https://safepay-docs.netlify.app/developers/webhooks/webhook-types Examples of JSON payloads sent for different subscription-related webhook events. ```APIDOC ## subscription.paused ### Description Triggered when a subscription status changes to PAUSED. ### Payload Example { "token": "evt_3ebf1fea-b065-4a7d-925c-199245f98114", "version": "2.0.0", "type": "subscription.paused", "data": { "id": "sub_7e48edb7-daf8-47bf-9679-5b1cf24ff614", "status": "PAUSED" } } ## subscription.resumed ### Description Triggered when a subscription status changes to ACTIVE after being paused. ### Payload Example { "token": "evt_9e0c9f81-8607-4fd7-936c-56fed465ee90", "version": "2.0.0", "type": "subscription.resumed", "data": { "id": "sub_5726bec7-1d2a-424d-a650-04b963c0e854", "status": "ACTIVE" } } ## subscription.payment.succeeded ### Description Triggered when a subscription payment is successfully processed. ### Payload Example { "token": "evt_ea9ab1a2-4a3b-478a-ac82-cb986b60242e", "version": "2.0.0", "type": "subscription.payment.succeeded", "data": { "id": "sub_73f6b269-4c8e-44d6-b55e-b982ef5f2835", "transaction_status": "COMPLETE" } } ## subscription.payment.failed ### Description Triggered when a subscription payment attempt fails. ### Payload Example { "token": "evt_3f8ee089-c083-4475-af48-036b38140053", "version": "2.0.0", "type": "subscription.payment.failed", "data": { "id": "sub_b55072cf-2556-4c17-82b4-dae075960df8", "transaction_status": "FAILED", "transaction_error_message": "unrecognized or unsupported action kind" } } ``` -------------------------------- ### Basic Input Usage Source: https://safepay-docs.netlify.app/components/Input Demonstrates how to import and implement the Input component within a React application. ```jsx import React from 'react'; import { Input } from '~/ui/components/Form'; export default function App() { return (
); } ``` -------------------------------- ### Reversal API response structure Source: https://safepay-docs.netlify.app/modify-payments/reversal Example of a successful JSON response returned by the Reversal API. ```json { "data": { "tracker": { "token": "track_9d765b77-608f-46bc-84d2-5f4392753ca3", "client": "sec_edeade52-46aa-483b-b87d-009d3ce41554", "environment": "sandbox", "state": "TRACKER_REVERSED", "intent": "CYBERSOURCE", "mode": "instrument", "next_actions": { "CYBERSOURCE": { "kind": "NOOP", "request_id": "req_55e5ef0a-9081-498b-80b2-ce65f5f0efda" } }, "purchase_totals": { "quote_amount": { "currency": "PKR", "amount": 100 }, "base_amount": { "currency": "PKR", "amount": 100 }, "conversion_rate": { "base_currency": "PKR", "quote_currency": "PKR", "rate": 1 } } }, "action": {} }, "status": { "errors": [], "message": "success" } } ``` -------------------------------- ### Authentication Enrollment Response Source: https://safepay-docs.netlify.app/build-your-integration/advanced-checkout/cardinal Example JSON response structure for a successful payer authentication enrollment. ```JSON { "action": { "token": "req_29ffd60c-0527-4173-920b-968175deac28", "payer_authentication_enrollment": { "access_token": "eyJ...", "authentication_transaction_id": "BaQGS1iS5DqhxSPWukG0", "payload": "eyJtZXNzYWdlVHlwZSI6IkNSZXEi..." } } } ``` -------------------------------- ### POST /order/payments/v3/{tracker_id} (PAYER_AUTH_SETUP) Source: https://safepay-docs.netlify.app/developers/payment-journeys/customer Initiates the payer authentication process by performing the PAYER_AUTH_SETUP action. ```APIDOC ## POST /order/payments/v3/{tracker_id} ### Description Initiates the payer authentication process. If using raw payment entry mode, payment method details must be provided. ### Method POST ### Endpoint https://sandbox.api.getsafepay.com/order/payments/v3/{tracker_id} ### Request Body - **payload.payment_method.card** (object) - Required - Contains card_number, expiration_month, expiration_year, and cvv. ``` -------------------------------- ### GET /customers/v1/{customerToken}/wallet/ Source: https://safepay-docs.netlify.app/concepts/tokenization/manage-tokens Retrieves a list of all payment details stored for a specific shopper. ```APIDOC ## GET /customers/v1/{customerToken}/wallet/ ### Description Retrieves a list of all payment details stored for a shopper. ### Method GET ### Endpoint /customers/v1/{customerToken}/wallet/ ### Parameters #### Path Parameters - **customerToken** (string) - Required - The unique identifier for the customer. #### Query Parameters - **limit** (number) - Required - The upper bound on the number of results. - **page** (number) - Required - The offset from which to fetch limit many results. ### Response #### Success Response (200) - **data** (object) - Contains the list of wallet items and the count. - **status** (object) - Contains error information and success message. #### Response Example { "data": { "wallet": [ { "token": "pm_bea00774-22ba-44ce-82c5-3cdd1a342e89", "customer": "cus_2fc20245-e0f8-447f-af75-fa651cfd54aa", "merchant_api_key": "sec_edeade52-46aa-483b-b87d-009d3ce41554", "kind": 1, "max_usage": 1, "usage_interval": 0, "is_deleted": false, "cybersource": { "token": "tms_b8543301-95ad-4eae-a86f-8d90a5ece0c7", "customer_payment_method": "pm_bea00774-22ba-44ce-82c5-3cdd1a342e89", "scheme": 2, "bin": "520000", "last_four": "1096", "expiry_month": "12", "expiry_year": "2023", "created_at": { "seconds": 1697697321 }, "updated_at": { "seconds": 1697697321 } }, "usage_count": 0, "expires_at": { "seconds": 1697783722 }, "created_at": { "seconds": 1697697321 }, "updated_at": { "seconds": 1697697321 } } ], "count": 1 }, "status": { "errors": [], "message": "success" } } ``` -------------------------------- ### Create a Tracker Source: https://safepay-docs.netlify.app/developers/payment-journeys/customer Initiate a payment session by creating a tracker associated with a customer. This request should be performed server-side. ```cURL // For live payments use https://api.getsafepay.com curl --location 'https://sandbox.api.getsafepay.com/order/payments/v3/' \ --data '{ "merchant_api_key": "sec_ed8fa26a-e36d-49d2-89bd-1c72c8b5c133", "user" : "cus_e927d58d-3796-4f36-a209-384906d712ea", "intent": "CYBERSOURCE", "mode": "payment", "currency": "PKR", "amount": 100000 }' ``` -------------------------------- ### Create a payment session with Node.js Source: https://safepay-docs.netlify.app/build-your-integration/advanced-checkout/introduction Initializes a payment session using the Safepay Node.js SDK to prepare for customer checkout. ```javascript const safepay = require('@sfpy/node-core')('YOUR_SECRET_KEY', { authType: 'secret', host: 'https://sandbox.api.getsafepay.com' // for live payments use https://api.getsafepay.com }); try { const response = safepay.payments.session.setup({ "merchant_api_key": "YOUR_API_KEY", "user": "cust_a7cc6fc1-088d-4f35-9dac-2bab2cb234a1", "intent": "CYBERSOURCE", "mode": "payment", "entry_mode": "raw", "currency": "USD", "amount": 10000, "metadata": { "order_id": "1234567890" } }) } catch (err) { console.log(error); } ``` -------------------------------- ### POST /order/payments/v3/track_{tracker_id} (PAYER_AUTH_SETUP) Source: https://safepay-docs.netlify.app/developers/tokenization/customer Initiates the payer authentication process by performing the PAYER_AUTH_SETUP action. ```APIDOC ## POST /order/payments/v3/track_{tracker_id} ### Description Initiates the payer authentication process. If the tracker has the raw payment entry mode set, payment method details must be provided. ### Method POST ### Endpoint https://sandbox.api.getsafepay.com/order/payments/v3/track_{tracker_id} ### Request Body - **payload** (object) - Required - Contains payment method details. ### Request Example { "payload": { "payment_method": { "card": { "card_number": "5200000000001096", "expiration_month": "12", "expiration_year": "2028", "cvv": "123" } } } } ``` -------------------------------- ### Fetch Payment Status with Node.js Source: https://safepay-docs.netlify.app/build-your-integration/express-checkout Initialize the Safepay client and fetch the payment tracker details using the tracker token. ```javascript const safepay = require('@sfpy/node-core')('SAFEPAY_SECRET_KEY', { authType: 'secret', host: 'https://sandbox.api.getsafepay.com' // for live payments use https://api.getsafepay.com }); try { const response = safepay.reporter.payments.fetch(trackerToken) } catch (err) { console.log(error); } ``` -------------------------------- ### GET /customers/v1/{customerToken}/wallet/{paymentMethodToken} Source: https://safepay-docs.netlify.app/concepts/tokenization/manage-tokens Retrieves a single stored payment method for a specific customer. ```APIDOC ## GET /customers/v1/{customerToken}/wallet/{paymentMethodToken} ### Description Retrieves a single stored payment method for a shopper. ### Method GET ### Endpoint /customers/v1/{customerToken}/wallet/{paymentMethodToken} ### Parameters #### Path Parameters - **customerToken** (string) - Required - The unique identifier for the customer. - **paymentMethodToken** (string) - Required - The unique identifier for the payment method. ### Response #### Success Response (200) - **data** (object) - The payment method details. - **status** (object) - The response status including errors and message. #### Response Example { "data": { "token": "pm_bea00774-22ba-44ce-82c5-3cdd1a342e89", "customer": "cus_2fc20245-e0f8-447f-af75-fa651cfd54aa", "merchant_api_key": "sec_edeade52-46aa-483b-b87d-009d3ce41554", "kind": 1, "max_usage": 1, "usage_interval": 0, "is_deleted": false, "cybersource": { "token": "tms_b8543301-95ad-4eae-a86f-8d90a5ece0c7", "customer_payment_method": "pm_bea00774-22ba-44ce-82c5-3cdd1a342e89", "scheme": 2, "bin": "520000", "last_four": "1096", "expiry_month": "12", "expiry_year": "2023", "created_at": { "seconds": 1697697321 }, "updated_at": { "seconds": 1697697321 } }, "usage_count": 0, "expires_at": { "seconds": 1697783722 }, "created_at": { "seconds": 1697697321 }, "updated_at": { "seconds": 1697697321 } }, "status": { "errors": [], "message": "success" } } ``` -------------------------------- ### Download Cardinal SDK via cURL Source: https://safepay-docs.netlify.app/build-your-integration/advanced-checkout/cardinal Use these commands to download the CardinalMobile framework package from the JFrog repository. ```bash # Install the Cardinal SDK curl -L -u : https://cardinalcommerceprod.jfrog.io/artifactory/ios/-/cardinalmobilesdk.zip -o # Example: curl -L -u UserName:ApiKey "https://cardinalcommerceprod.jfrog.io/artifactory/ios/2.2.5-6/cardinalmobilesdk.zip" -o cardinalmobilesdk.zip ``` -------------------------------- ### GET /reporter/api/v1/payments/{tracker} Source: https://safepay-docs.netlify.app/build-your-integration/express-checkout?platform-=react-native Retrieves the current status and details of a payment session using the tracker token. ```APIDOC ## GET /reporter/api/v1/payments/{tracker} ### Description Retrieves the payment session details using the tracker token obtained from the return URL. ### Method GET ### Endpoint /reporter/api/v1/payments/{tracker} ### Parameters #### Path Parameters - **tracker** (string) - Required - The unique tracker token associated with the payment session. ### Response #### Success Response (200) - **data.tracker.state** (string) - The current state of the tracker. A value of 'TRACKER_ENDED' indicates successful completion. - **data.tracker.token** (string) - The tracker token. #### Response Example { "data": { "tracker": { "token": "track_1a46dc70-91f9-4892-8e25-0bb5205b69c7", "state": "TRACKER_ENDED" } }, "status": { "message": "success" } } ``` -------------------------------- ### payment.failed webhook payload Source: https://safepay-docs.netlify.app/developers/webhooks/webhook-types Example JSON payload for a failed payment event, including error category and message. ```json { "token":"evt_e7069e13-e4a4-4518-b5ce-ee42e62b6797", "version":"2.0.0", "merchant_api_key":"sec_edeade52-46aa-483b-b87d-009d3ce41554", "type":"payment.failed", "endpoint":"http://example.com", "data":{ "tracker":"track_138cf593-3d3f-4d54-b9c6-27a510afb780", "intent":"CYBERSOURCE", "state":"TRACKER_ENROLLED", "customer_email":"hzee@gmail.com", "metadata":{}, "category":"PAYMENT_METHOD_ERROR", "code":403, "message":"The card you have used has been flagged as either stolen or lost. ", "failed_at":{ "seconds":1698754648, "nanos":494424793 } }, "created_at":{ "seconds":1698754648, "nanos":589390626 } } ``` -------------------------------- ### Example response for listWallet endpoint Source: https://safepay-docs.netlify.app/concepts/tokenization/manage-tokens The response structure returned by the listWallet endpoint containing customer payment methods. ```json { "data": { "wallet": [ { "token": "pm_bea00774-22ba-44ce-82c5-3cdd1a342e89", "customer": "cus_2fc20245-e0f8-447f-af75-fa651cfd54aa", "merchant_api_key": "sec_edeade52-46aa-483b-b87d-009d3ce41554", "kind": 1, "max_usage": 1, "usage_interval": 0, "is_deleted": false, "cybersource": { "token": "tms_b8543301-95ad-4eae-a86f-8d90a5ece0c7", "customer_payment_method": "pm_bea00774-22ba-44ce-82c5-3cdd1a342e89", "scheme": 2, "bin": "520000", "last_four": "1096", "expiry_month": "12", "expiry_year": "2023", "created_at": { "seconds": 1697697321 }, "updated_at": { "seconds": 1697697321 } }, "usage_count": 0, "expires_at": { "seconds": 1697783722 }, "created_at": { "seconds": 1697697321 }, "updated_at": { "seconds": 1697697321 } } ], "count": 1 }, "status": { "errors": [], "message": "success" } } ```