diff --git a/cards/concepts.mdx b/cards/concepts.mdx index b8ab122..0436a19 100644 --- a/cards/concepts.mdx +++ b/cards/concepts.mdx @@ -10,6 +10,7 @@ and what to expect of them. This is not an extensive guide and we encourage you to use this document as a way to start your journey. Both VISA and Mastercard have great resources and guides that you can also use. +<<<<<<< HEAD For transaction-related concepts like payments, refunds, and reversals, see our dedicated [Card Transactions](/transactions) guide. @@ -56,6 +57,53 @@ and undergo through different analysis to reach a conclusion. 2. **Investigation**: Review transaction details and evidence 3. **Provisional Credit**: Temporary refund while investigating 4. **Resolution**: Final decision and permanent credit/debit +======= +## Authorizations + +When a card is used to make a purchase, an authorization request is created, which can be approved or declined. +The process to authorize transactions takes into consideration a lot of factors, some are: + +- The card balance has enough funds to cover the transaction amount +- The card is active, with enough spending limits +- Risk/AML screening +- Anti-fraud analysis, and so on. + +If the authorization is approved, we deduct the amount from your card wallet and hold it in reserve until +the authorization is either captured, canceled, or expired without a capture. +In case it's not captured, unused funds will return to your card wallet. + +There are a few other edge cases that you should be ready to handle: + +1. **Partial authorizations**: used to increase the amount authorized. +2. **Incremental authorizations**: hotels can send more authorizations to cover for fees after checking out. +3. **Partial reversals**: used to reduce the amount authorized. + +Once an authorization is approved, it will be captured and becomes a transaction. + +## Transactions + +An authorization is captured and becomes a transaction usually under 24h. +But as with everything in the card universe, this has edge cases. +Car rentals, hotels, and some other businesses (defined by MCC) can capture up to a month +after the authorization event. + +Again, more edge cases to handle: + +1. **Refunds**: unlike what you'd expect, this is not directly related to an authorization. +2. **Partial capture**: a capture happens with an amount lower than the authorized amount. +3. **Over capture**: some MCCs can over capture, meaning they can capture a value higher than the authorized amount. +4. **Multi capture**: basically multiple partial captures on a single authorization, limited to some MCCs as well. +5. **Force capture**: sometimes you receive a capture on a rejected authorization (yes, really), for example, some POS terminals on planes are not connected to the internet and when the plane lands it sends the transactions that happened mid-flight. + +These edge cases are limited to some MCCs, but they can be used for fraudulent behaviour. +That's why we have the dispute process to contest suspicious transactions. + +## Disputes + +Disputes are used to recover funds for captured transactions. Their main use-case is to revert fraudulent transactions +or problems with the product or service paid for. Fraud and non-fraud disputes have different requirements and rules, +and undergo through different analysis to reach a conclusion. +>>>>>>> ce2d52e (Separate card order state transitions) ## Card PINs diff --git a/cards/create-physical-cards.mdx b/cards/create-physical-cards.mdx index 6ae1be3..38772ff 100644 --- a/cards/create-physical-cards.mdx +++ b/cards/create-physical-cards.mdx @@ -10,7 +10,11 @@ description: "Order physical cards for your Users." +<<<<<<< HEAD [This endpoint creates a new `CardOrder` with the status of `PENDINGTRANSACTION`](/api-reference/physical-card-order/create-physical-card-order): +======= +[This endpoint creates a new `CardOrder` with the status of `PENDINGTRANSACTION`](/api-reference/card-order/create-a-new-card-order): +>>>>>>> ce2d52e (Separate card order state transitions) ```bash cURL curl -X POST /api/v1/order/create @@ -76,7 +80,11 @@ The conditions for the payment are: If all the conditions above are met, the `CardOrder.status` is set to `READY`. +<<<<<<< HEAD [Finally, you can create the Physical Card](/api-reference/physical-card-order/create-a-physical-card): +======= +[Finally, you can create the Physical Card](/api-reference/card-order/create-a-card-out-of-a-card-order): +>>>>>>> ce2d52e (Separate card order state transitions) ```bash cURL curl -X POST /api/v1/order/:orderId/create-card diff --git a/docs.json b/docs.json index 607aaff..258c3f9 100644 --- a/docs.json +++ b/docs.json @@ -1,6 +1,7 @@ { "theme": "mint", "name": "Gnosis Pay Documentation", + "versions": ["v2", "v1"], "colors": { "primary": "#707A2D", "light": "#D8EB81", @@ -8,90 +9,154 @@ }, "favicon": "/static/img/favicon.ico", "navigation": { - "tabs": [ + "versions": [ { - "tab": "Guides", - "groups": [ + "version": "v2", + "tabs": [ { - "group": "Introduction to Gnosis Pay", - "icon": "play", - "pages": ["index", "integration-model", "auth", "onboarding-flow"] - }, - { - "group": "Accounts", - "icon": "user", - "pages": [ - "account", - "account/update-authenticated-account", - "account/adding-safe-owner" - ] - }, - { - "group": "On/Off Ramps", - "icon": "landmark", - "pages": [ - "on-off-ramps/index", - "on-off-ramps/iban-integration", - "on-off-ramps/kyc-sharing" - ] - }, - { - "group": "Cards", - "icon": "credit-card", - "pages": [ - "cards/concepts", - "cards/create-physical-cards", - "cards/create-virtual-cards", - "cards/card-order-state-transitions", - "cards/pse-integration" - ] - }, - { - "group": "Card Transactions", - "icon": "receipt", - "pages": [ - "transactions/index", - "transactions/lifecycle", - "transactions/integration-guide" - ] - }, - { - "group": "On-chain", - "icon": "cubes", - "pages": [ - "gp-onchain/overview", - "gp-onchain/about-GP-safe", - "gp-onchain/sign-message", - "gp-onchain/daily-limit", - "gp-onchain/withdraw-funds-from-safe", - "gp-onchain/third-party-bridges" + "tab": "Guides", + "groups": [ + { + "group": "Getting Started", + "icon": "play", + "pages": [ + "v2/v2-overview", + "v2/v1-v2-diff", + "v2/v2-siwe-auth", + "v2/v2-onboard" + ] + }, + { + "group": "GP On-chain", + "icon": "cube", + "pages": [ + "v2/gp-onchain/v2-account", + "v2/gp-onchain/v2-account-statement", + "v2/gp-onchain/v2-withdraw" + ] + }, + { + "group": "Card", + "icon": "credit-card", + "pages": [ + "v2/cards/v2-virtual-card", + "v2/cards/v2-card-details", + "v2/cards/v2-simulate-card", + "v2/cards/v2-pse-integration" + ] + }, + { + "group": "Webhooks", + "icon": "webhook", + "pages": ["v2/webhooks/webhook", "v2/webhooks/webhook-events"] + } ] }, { - "group": "Webhooks", - "icon": "webhook", - "pages": [ - "webhooks/introduction", - "webhooks/getting-started", - "webhooks/events" + "tab": "API Reference", + "groups": [ + { + "group": "V2 Production API", + "openapi": "https://gp-auth-module.prod.gnosispay.com/openapi.json", + "collapsed": true + } ] } ] }, { - "tab": "API reference", - "groups": [ + "version": "v1", + "tabs": [ { - "group": "Authentication", - "pages": ["api-reference/intro", "api-reference/auth-app"] - }, - { - "group": "API reference", - "openapi": "https://api.gnosispay.com/api-docs/spec.json" + "tab": "Guides", + "groups": [ + { + "group": "Introduction to Gnosis Pay", + "icon": "play", + "pages": [ + "v1/overview", + "v1/integration-model", + "v1/auth", + "v1/quickstart" + ] + }, + { + "group": "Accounts", + "icon": "user", + "pages": [ + "v1/account/index", + "v1/account/update-authenticated-account", + "v1/account/adding-safe-owner" + ] + }, + { + "group": "On/Off Ramps", + "icon": "landmark", + "pages": [ + "v1/on-off-ramps/index", + "v1/on-off-ramps/iban-integration", + "v1/on-off-ramps/kyc-sharing" + ] + }, + { + "group": "Cards", + "icon": "credit-card", + "pages": [ + "v1/cards/concepts", + "v1/cards/create-physical-cards", + "v1/cards/create-virtual-cards", + "v1/cards/card-order-state-transitions", + "v1/cards/pse-integration" + ] + }, + { + "group": "Card Transactions", + "icon": "receipt", + "pages": [ + "v1/transactions/index", + "v1/transactions/lifecycle", + "v1/transactions/integration-guide" + ] + }, + { + "group": "On-chain", + "icon": "cubes", + "pages": [ + "v1/gp-onchain/overview", + "v1/gp-onchain/about-GP-safe", + "v1/gp-onchain/sign-message", + "v1/gp-onchain/daily-limit", + "v1/gp-onchain/withdraw-funds-from-safe", + "v1/gp-onchain/third-party-bridges" + ] + }, + { + "group": "Webhooks", + "icon": "webhook", + "pages": [ + "v1/webhooks/introduction", + "v1/webhooks/getting-started", + "v1/webhooks/events" + ] + } + ] }, { - "group": "PSE API", - "openapi": "https://api-pse-public.gnosispay.com/api-docs/spec.json" + "tab": "API reference", + "groups": [ + { + "group": "Authentication", + "pages": ["v1/api-reference/intro", "v1/api-reference/auth-app"] + }, + { + "group": "API reference", + "openapi": "https://api.gnosispay.com/api-docs/spec.json" + }, + { + "group": "PSE API", + "openapi": "https://api-pse-public.gnosispay.com/api-docs/spec.json" + } + ] } ] } diff --git a/v1/account/adding-safe-owner.mdx b/v1/account/adding-safe-owner.mdx new file mode 100644 index 0000000..49b5d5e --- /dev/null +++ b/v1/account/adding-safe-owner.mdx @@ -0,0 +1,63 @@ +--- +title: "Managing Safe Ownership" +description: "Add a new owner to a Gnosis Pay Safe Account" +--- + +Adding a new owner to a Gnosis Pay Safe registers that account as a **Delay Module owner**. +Only Delay Module owners can approve and execute on-chain transactions. + + +**Important distinction:** +- **Authenticated wallets** are linked to a Gnosis Pay user for API access (via SIWE and JWT). +- **Safe owners (Delay Module owners)** are accounts explicitly added on-chain to the Safe. +Authenticated wallets do **not** become Safe owners unless they are also as owners for the safe. + + +This guide walks through the process of adding an additional Safe owner. Once complete, the new owner will be able to approve and execute transactions through the Delay Module. + + + + Follow the [authentication flow](https://docs.gnosispay.com/auth) to obtain a JWT token for the Gnosis Pay user. + + + + Call [this endpoint](https://docs.gnosispay.com/api-reference/safe-owners/get-typed-data-for-adding-a-new-safe-owner) to receive the typed data. + Sign the typed data with the current Safe owner’s key to produce a signature. + + ```bash + curl --request GET \ + --url https://api.gnosispay.com/api/v1/owners/add/transaction-data \ + --header "Authorization: Bearer " + ``` + + + + Send the new owner’s address, the signature, and the signed message to [this endpoint](https://docs.gnosispay.com/api-reference/safe-owners/add-a-new-owner-to-the-safe). + + ```bash + curl --request POST \ + --url https://api.gnosispay.com/api/v1/owners \ + --header "Authorization: Bearer " \ + --header "Content-Type: application/json" \ + --data '{ + "newOwner": "0x3270bf32AB647e90eF94A026c70Aa1daaaDA2382", + "signature": "0x1234567890abcdef...", + "message": { + "salt": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "data": "0xa9059cbb0000000000000000000000003270bf32ab647e90ef94a026c70aa1daaaada2382" + } + }' + ``` + The operation is processed through the Delay Relay and executes after a 3-minute delay. + + + + Confirm that the new owner was added to the Delay Module by checking the [Safe’s owner list](https://docs.gnosispay.com/api-reference/safe-owners/get-the-list-of-safe-owners). + + ```bash + curl --request GET \ + --url https://api.gnosispay.com/api/v1/owners \ + --header "Authorization: Bearer " + ``` + + diff --git a/v1/account/index.mdx b/v1/account/index.mdx new file mode 100644 index 0000000..7bfb23d --- /dev/null +++ b/v1/account/index.mdx @@ -0,0 +1,108 @@ +--- +title: "Accounts on Gnosis Pay" +description: "How the Gnosis Pay Safe works" +--- + +When a user signs up for Gnosis Pay, a new **Gnosis Pay Safe** a smart contract wallet is created on-chain. +This Safe holds the user’s funds and is controlled only by its **owners**. + +A Gnosis Pay Safe owner can be either: +- an **EOA (Externally Owned Account)**, or +- another **smart wallet** (e.g. a Safe) whose owners may use passkeys, EOAs, or other signers. + +Funds in a Gnosis Pay Safe are never held by Gnosis Pay or any third party; ownership and control remain entirely with the Safe owners. + + + + + +--- + +## Authenticating sessions with wallets + +To access the Gnosis Pay dashboard or APIs, a wallet must authenticate using [Sign-In With Ethereum (SIWE)](https://docs.login.xyz/). +After SIWE, a JWT token is issued and used to authorize API calls (e.g. ordering cards, fetching user info, or linking additional authenticated wallets). + +Authenticated wallets are used **only for login and API sessions**. They do not perform on-chain actions and may or may not overlap with the Safe owners. + + +The first wallet connected during setup is automatically registered as both an **authenticated wallet** and the **initial Safe owner** (via the Delay Module). + + +Follow the guide on [adding an authenticated wallet](account/update-authenticated-account) for step-by-step instructions. + +--- + +## Safe Smart Account + +Each Gnosis Pay user is assigned a **Safe Smart Account**, a self-custodied smart contract wallet deployed on Gnosis Chain (L1). +Currently, a new Safe is deployed for every user. Support for connecting an existing Safe multisig is planned. + +### What is a smart contract wallet? + +Smart contract wallets are contracts that manage assets on-chain with programmable rules. +They enable advanced security and automation beyond EOAs. + +[Safe](https://safe.global/) is the leading smart contract wallet, securing over $70B in assets. + +### Exploring the Safe setup + +Users can view their Safe configuration in the [Safe web app](https://app.safe.global/) via the Zodiac app: + +1. Open the Gnosis Pay Dashboard. +2. Click **“View all transactions here”** to open the Safe web app. +3. In the sidebar, select **Applications**. +4. Search for **Zodiac**. + +The **Roles Module** and **Delay Module** are open-source contracts licensed under LGPL 3.0. + +--- + +## Modules + +Modules extend Safe functionality with custom logic. +In Gnosis Pay, modules enforce spending rules and transaction flows while keeping user funds in self-custody. + +These modules follow the [Zodiac standard](https://gnosisguild.org/zodiac/) developed by Gnosis Guild. + +--- + +## Roles Module + +The Roles Module enforces which actions Gnosis Pay can perform on behalf of the user. It defines: + +1. **Token used** → which token Gnosis Pay can spend. +2. **Daily limit** → maximum amount spendable per day. +3. **Recipient address** → destination for allowed transfers (e.g. the issuer’s settlement Safe). +4. **Role delegation** → assigns these permissions to Gnosis Pay. + +Only Safe owners can update these rules. +For example, a user may adjust the daily spending limit at any time. + +--- + +## Delay Module + +The Delay Module enforces a **3-minute delay** for all non-card transactions (e.g. transfers, deposits). +This ensures funds remain available for card payments and prevents race conditions. + + +During the 3-minute delay, the card is paused if any non-card transactions are pending. + + +The Delay Module also ensures the user’s EOA retains ultimate control. +During activation, the EOA becomes an indirect Safe owner via the Delay Module. + +⚠️ Reconfiguring or removing the Delay Module may prevent Gnosis Pay from functioning properly. + +--- + +## What happens if I lose access to my EOA Wallet? + +If you’ve forgotten the password to your EOA Wallet, you can regain access using its seed phrase. + + +However, if you’ve lost access to the seed phrase and cannot regain access to the EOA, you will also lose access to the Safe if it’s the only owner. + + +**To mitigate this risk, consider using a [Safe](https://safe.global/) with multiple owners instead of an EOA.** \ No newline at end of file diff --git a/v1/account/update-authenticated-account.mdx b/v1/account/update-authenticated-account.mdx new file mode 100644 index 0000000..347b59d --- /dev/null +++ b/v1/account/update-authenticated-account.mdx @@ -0,0 +1,45 @@ +--- +title: "Adding a new wallet for authentication" +description: "Link an additional wallet address to a Gnosis Pay user" +--- + +A Gnosis Pay user can have multiple authenticated wallets attached to their account. +Authenticated wallets are used to sign in via SIWE and to start new API sessions. + + + + Follow the [authentication flow](https://docs.gnosispay.com/auth) to obtain a JWT token for the Gnosis Pay user. + + + + Make a POST call to [this endpoint](https://docs.gnosispay.com/api-reference/account-management/create-a-new-eoa-account-for-the-current-user) with the address to add. + + ```bash + curl --request POST \ + --url https://api.gnosispay.com/api/v1/eoa-accounts \ + --header "Authorization: Bearer " \ + --header "Content-Type: application/json" \ + --data '{ + "address": "0x1234567890abcdef1234567890abcdef12345678" + }' + ``` + + + + Call the [list accounts endpoint](https://docs.gnosispay.com/api-reference/account-management/retrieve-the-eoa-accounts-for-the-current-user). + The new address should appear in the response. + + ```bash + curl --request GET \ + --url https://api.gnosispay.com/api/v1/eoa-accounts \ + --header "Authorization: Bearer " + ``` + + + + +- Adding an **authenticated wallet** only links it to a Gnosis Pay user for login and API sessions. +- An authenticated wallet is **not automatically a Safe owner**. +- Only Safe owners (EOAs or smart wallets added to the Safe) can interact with the Delay Module or execute on-chain actions. +- Authenticated wallets can use the API (e.g. place card orders, fetch user info) but **cannot control funds** unless also added as Safe owners. + diff --git a/v1/api-reference/auth-app.mdx b/v1/api-reference/auth-app.mdx new file mode 100644 index 0000000..8949e78 --- /dev/null +++ b/v1/api-reference/auth-app.mdx @@ -0,0 +1,26 @@ +--- +title: Authentication Helper App +description: Use this app to generate and sign a message using your ethereum wallet. +--- + +export const AuthApp = () => { + return ( +
+
+