Safepay

https://safepay-docs.netlify.app
Admin
Safepay is a secure, flexible payment gateway and processing platform that enables developers to...
Tokens:58,348
Snippets:541
Trust Score:7.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### 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 (
    <div>
      <h1>Project Files</h1>
      <FileTree files={files} />
    </div>
  );
}
```

--------------------------------

### 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 (
    <div>
      <Step label="1">
        This is the first step of the process
      </Step>
      <Step label="2">
        Here's what you need to do for the second step.
      </Step>
    </div>
  );
}
```

--------------------------------

### 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 (
      <div style={styles.container}>
        <p>Button Example</p>
        <Button
          size="lg"
          theme="primary"
          leftSlot={<PaletteIcon />}
          disabled={false}
          onClick={() => console.log("button clicked")}
        >
          I am a clickable button
        </Button>
      </div>
    );
  }
```

--------------------------------

### 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 (
    <div>
      <Input
        type="text"
        placeholder="Enter your name"
        name="username"
      />
    </div>
  );
}
```

--------------------------------

### 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 <USER_NAME>:<API_KEY> https://cardinalcommerceprod.jfrog.io/artifactory/ios/<VERSION>-<BUILD_NUMBER>/cardinalmobilesdk.zip -o <LOCAL_FILE_NAME.EXT>
# 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"
  }
}
```
Tokens:
Raw