Mattilda Pay

https://docs.mattildapayments.com
Admin
Mattilda Pay is a payment processing platform that enables developers to accept cards, digital...
Tokens:337,538
Snippets:1,515
Trust Score:4.8
Update:8 months ago
Show doc for...
Tokens:
Raw
### Example Report Creation

Source: https://docs.mattildapayments.com/guides/dashboard/reports/models-transactions

An example demonstrating how to create a report using the transactions model, including specifying fields, filters, and sorting.

```APIDOC
## Example

Example of report creation using the `transactions` model.

```json
{
  "name": "Test report",
  "spec": {
    "model": "transactions",
    "params": {
      "fields": ["id", "created_at"],
      "filters": {
        "status": ["capture_succeeded"]
      },
      "sort": [
        {
          "field": "created_at",
          "order": "desc"
        }
      ]
    }
  }
}
```
```

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

### Example Transaction Report Configuration

Source: https://docs.mattildapayments.com/guides/dashboard/reports/models-transactions

An example JSON object demonstrating how to configure a transaction report with specific fields, filters, and sorting parameters.

```json
{
  "name": "Test report",
  "spec": {
    "model": "transactions",
    "params": {
      "fields": ["id", "created_at"],
      "filters": {
        "status": ["capture_succeeded"]
      },
      "sort": [
        {
          "field": "created_at",
          "order": "desc"
        }
      ]
    }
  }
}
```

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

### CDN Embed Theming Example

Source: https://docs.mattildapayments.com/guides/payments/embed/theming

Shows how to configure the Embed component with a custom theme when using the CDN integration. The `setup` function accepts a theme object to customize the appearance.

```javascript
setup({
  gr4vyId: "mattilda",
  element: ".container",
  amount: 1299,
  country: 'AU',
  currency: "MXN",
  token: token,
  theme: {
    colors: {
      primary: "green",
      text: "black",
    },
    borderWidths: {
      input: "thick",
    },
    radii: {
      input: "none",
    }
  }
});
```

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

### Install Gr4vy CLI using npm

Source: https://docs.mattildapayments.com/guides/tools

This command installs the Gr4vy CLI globally on your system using Node Package Manager (npm). Ensure you have Node.js installed before running this command. This is the first step to using the CLI for development and testing.

```bash
npm install -g @gr4vy/cli

```

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

### Install Secure Fields (React, Node.js, CDN)

Source: https://docs.mattildapayments.com/guides/payments/secure-fields/quick-start/embed

Instructions for installing the Secure Fields library. Choose the method that best suits your project setup: npm or yarn for React and Node.js, or a CDN link for direct script inclusion.

```bash
npm install @gr4vy/secure-fields-react --save
# or: yarn add @gr4vy/secure-fields-react
```

```bash
npm install @gr4vy/secure-fields --save
# or: yarn add @gr4vy/secure-fields
```

```html
<script src="https://cdn.mattildapayments.com/secure-fields/latest/secure-fields.js"></script>
<link
  rel="stylesheet"
  href="https://cdn.mattildapayments.com/secure-fields/latest/secure-fields.css"
/>
```

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

### Install iOS SDK using CocoaPods

Source: https://docs.mattildapayments.com/guides/payments/ios/quick-start/ios

Command to install the specified SDK dependencies defined in the Podfile. For users with M1 Macs, a specific command including 'arch -x86_64' is required to ensure compatibility.

```shell
pod install
```

```shell
arch -x86_64 pod install
```

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

### Get Payment Options List (Go)

Source: https://docs.mattildapayments.com/guides/payments/direct-api/quick-start/payment-options

Sets up the Gr4vy Go SDK and invokes the PaymentOptions.List method to fetch checkout payment options. Requires context, authentication token, and SDK configuration.

```go
package main

import(
	"context"
	gr4vygo "github.com/gr4vy/gr4vy-go"
	"os"
	"github.com/gr4vy/gr4vy-go/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    privateKey := "...."
	withToken := gr4vy.WithToken(privateKey, []JWTScope{ReadAll, WriteAll}, 60)

	s := gr4vy.New(
		gr4vy.WithID("mattilda"),
		gr4vy.WithServer(gr4vy.ServerSandbox),
		gr4vy.WithSecuritySource(withToken),
		gr4vy.WithMerchantAccountID("example"),
	)

    res, err := s.PaymentOptions.List(ctx, components.PaymentOptionRequest{})
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        // handle response
    }
}
```

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

### Install Secure Fields using npm or yarn

Source: https://docs.mattildapayments.com/guides/payments/secure-fields/click-to-pay

Instructions for installing the Secure Fields library using either npm or yarn package managers. This is the first step before initializing the SDK in your project.

```bash
npm install @gr4vy/secure-fields --save
# or: yarn add @gr4vy/secure-fields
```

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

### Install Server-Side SDKs for Click to Pay

Source: https://docs.mattildapayments.com/guides/payments/secure-fields/click-to-pay

Install the Gr4vy server-side SDKs for various programming languages to prepare for Click to Pay integration. These SDKs are essential for securely generating checkout sessions on the server.

```csharp
dotnet add package Gr4vy
```

```go
go get github.com/gr4vy/gr4vy-go
```

```java
# Please check for the latest version
implementation 'com.gr4vy:sdk:1.0.0'
```

```php
composer require "gr4vy/gr4vy-php"
```

```python
pip install gr4vy
```

```typescript
npm install @gr4vy/sdk
# or: yarn add @gr4vy/sdk
```

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

### Get Transaction Details Example (JSON)

Source: https://docs.mattildapayments.com/guides/payments/direct-api/quick-start/status

This JSON object represents the details of a transaction, including its ID, status, amount, currency, and payment method. This is typically returned when fetching transaction details via the API.

```json
{
  "type": "transaction",
  "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "status": "authorized",
  "amount": 1299,
  "currency": "MXN",
  "payment_method": {
    "type": "payment-method",
    "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
    "method": "card",
    ...
  },
  ...
}
```

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

### Initialize and Prepare Gr4vy SDK in Android Activity

Source: https://docs.mattildapayments.com/guides/payments/android/quick-start/android

This Java code illustrates how to prepare and initialize the Gr4vy SDK within an Android activity. It includes declaring the SDK instance, initializing it in `onCreate`, registering an observer, and implementing the `Gr4vyResultHandler` interface.

```java
private lateinit var gr4vySDK: Gr4vySDK
```

```java
gr4vySDK = Gr4vySDK(activityResultRegistry, this, this)
```

```java
lifecycle.addObserver(gr4vySDK)
```

```java
class MainActivity : ComponentActivity(), Gr4vyResultHandler
```

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

### List Transactions with Gr4vy SDK in C#

Source: https://docs.mattildapayments.com/reference

Demonstrates how to initialize the Gr4vy SDK in C# and list transactions. It includes handling pagination by repeatedly calling `res.Next()` until all transactions are retrieved. This requires the Gr4vy SDK NuGet package.

```csharp
using Gr4vy;
using Gr4vy.Models.Components;
using Gr4vy.Models.Requests;

var sdk = new Gr4vySDK(
    id: "mattilda",
    server: SDKConfig.Server.Sandbox,
    bearerAuthSource: Auth.WithToken(privateKey),
    merchantAccountId: "default"
);

ListTransactionsRequest req = new ListTransactionsRequest() {};

ListTransactionsResponse? res = await sdk.Transactions.ListAsync(req);

while(res != null)
{
    // handle items

    res = await res.Next!();
}
```

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

### Get Shipping Details

Source: https://docs.mattildapayments.com/guides/features/webhooks/payload

Retrieves the shipping details for a specific buyer and order. This endpoint allows you to access information such as the buyer's name, contact details, and shipping address.

```APIDOC
## GET /websites/mattildapayments/shipping-details/{id}

### Description
Retrieves the shipping details for a specific buyer and order.

### Method
GET

### Endpoint
/websites/mattildapayments/shipping-details/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the shipping details.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **environment** (string) - The environment type (e.g., "sandbox").
- **target** (object) - Contains the shipping details.
  - **type** (string) - The type of target (e.g., "shipping-details").
  - **id** (string) - The unique identifier for the shipping details.
  - **buyer_id** (string) - The unique identifier for the buyer.
  - **first_name** (string) - The buyer's first name.
  - **last_name** (string) - The buyer's last name.
  - **email_address** (string) - The buyer's email address.
  - **phone_number** (string) - The buyer's phone number.
  - **address** (object) - The shipping address details.
    - **city** (string) - The city of the shipping address.
    - **country** (string) - The country of the shipping address.
    - **postal_code** (string) - The postal code of the shipping address.
    - **state** (string) - The state of the shipping address.
    - **state_code** (string) - The state code of the shipping address.
    - **house_number_or_name** (string) - The house number or name.
    - **line1** (string) - The first line of the street address.
    - **line2** (string) - The second line of the street address (optional).
    - **organization** (string) - The organization name.
  - **created_at** (string) - The timestamp when the shipping details were created.
  - **updated_at** (string) - The timestamp when the shipping details were last updated.

#### Response Example
```json
{
  "environment": "sandbox",
  "target": {
    "type": "shipping-details",
    "id": "3dda8d7a-e7cd-43b8-9128-21adf1ec868b",
    "buyer_id": "baa7b3b3-a4f1-49e3-afb0-0f41b48f5aa2",
    "first_name": "John",
    "last_name": "Smith",
    "email_address": "john@example.com",
    "phone_number": "+1234567890",
    "address": {
      "city": "Springfield",
      "country": "MX",
      "postal_code": "123456",
      "state": "CA",
      "state_code": "US-CA",
      "house_number_or_name": "21",
      "line1": "22nd Street",
      "line2": "",
      "organization": "mattilda"
    },
    "created_at": "2024-11-20T12:48:38.402474+00:00",
    "updated_at": "2024-11-20T12:48:38.402474+00:00"
  }
}
```
```

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

### Create a Report

Source: https://docs.mattildapayments.com/guides/dashboard/reports/how-to

Use the POST /reports/ API to create a new report. This endpoint allows you to define the report's name, parameters, sorting, and filters.

```APIDOC
## POST /reports/

### Description
Creates a new report with specified parameters, sorting, and filters.

### Method
POST

### Endpoint
/reports/

### Parameters
#### Request Body
- **name** (string) - Required - The name of the report.
- **spec** (object) - Required - The specification for the report.
  - **params** (object) - Required - Parameters for the report.
    - **fields** (array of strings) - Required - Fields to include in the report.
    - **sort** (array of objects) - Optional - Sorting criteria for the report.
      - **field** (string) - Required - The field to sort by.
      - **order** (string) - Required - The sort order ('asc' or 'desc').
    - **filters** (object) - Optional - Filters to apply to the report data.
      - **status** (array of strings) - Optional - Filter by transaction status.

### Request Example
```json
{
  "name": "Successful captures",
  "spec": {
    "params": {
      "fields": ["id", "captured_at", "amount"],
      "sort": [
        {
          "field": "created_at",
          "order": "asc"
        }
      ],
      "filters": {
        "status": ["capture_succeeded"]
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **type** (string) - The type of the object (e.g., "report").
- **id** (string) - The unique identifier for the report.
- **name** (string) - The name of the report.
- **created_at** (string) - The timestamp when the report was created.
- **updated_at** (string) - The timestamp when the report was last updated.
- **next_execution_at** (string|null) - The timestamp for the next scheduled execution.
- **description** (string|null) - A description for the report.
- **schedule** (string) - The report's schedule (e.g., "once").
- **schedule_enabled** (boolean) - Whether the schedule is enabled.
- **schedule_timezone** (string) - The timezone for the schedule.
- **spec** (object) - The specification of the report.
  - **model** (string) - The data model for the report.
  - **params** (object) - Parameters used for the report.
- **latest_execution** (object|null) - Details of the latest report execution.
  - **type** (string) - The type of the object (e.g., "report-execution").
  - **id** (string) - The unique identifier for the execution.
  - **created_at** (string) - The timestamp when the execution was created.
  - **updated_at** (string) - The timestamp when the execution was last updated.
  - **status** (string) - The status of the execution.
  - **context** (object) - Contextual information for the execution.

#### Response Example
```json
{
  "type": "report",
  "id": "71aa8d49-5ec7-43aa-b13c-9b16fdae0f9b",
  "name": "Successful captures",
  "created_at": "2022-10-28T10:15:36.547789+00:00",
  "updated_at": "2022-10-28T10:15:36.547789+00:00",
  "next_execution_at": null,
  "description": null,
  "schedule": "once",
  "schedule_enabled": false,
  "schedule_timezone": "Etc/UTC",
  "spec": {
    "model": "transactions",
    "params": {
      "sort": [
        {
          "field": "created_at",
          "order": "asc"
        }
      ],
      "fields": ["id", "captured_at", "amount"],
      "filters": {
        "method": null,
        "scheme": null,
        "status": ["capture_succeeded"],
        "currency": null,
        "metadata": null,
        "voided_at": null,
        "created_at": null,
        "captured_at": null,
        "authorized_at": null
      }
    }
  },
  "latest_execution": {
    "type": "report-execution",
    "id": "0848ef01-f44a-4564-abdb-52a1344bac63",
    "created_at": "2022-10-28T10:15:36.571232+00:00",
    "updated_at": "2022-10-28T10:15:36.611495+00:00",
    "status": "dispatched",
    "context": {
      "reference_timestamp": "2022-10-28T10:15:36.571232+00:00",
      "reference_timezone": "Etc/UTC"
    }
  }
}
```
```

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

### Example Payment Options Response

Source: https://docs.mattildapayments.com/guides/payments/direct-api/quick-start/payment-options

Demonstrates the structure of a successful response from the payment options API, detailing available payment methods with their types, icons, labels, and supported features.

```json
{
    "items": [
        {
            "type": "payment-option",
            "method": "card",
            "icon_url": "https://api.sandbox.mattildapayments.com/assets/icons/payment-methods/card.svg",
            "mode": "card",
            "label": "Card",
            "can_store_payment_method": true,
            "can_delay_capture": true,
            "context": {
                "approval_ui": {
                    "height": "589px",
                    "width": "500px"
                },
                "required_fields": {}
            }
        },
        {
            "type": "payment-option",

```

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

### Gr4vy CLI Autocomplete Command Usage

Source: https://docs.mattildapayments.com/guides/tools

This command provides instructions for enabling shell auto-completion for the Gr4vy CLI. You can specify the shell type (zsh, bash, powershell) to get tailored installation instructions. The `--refresh-cache` flag can be used to update the auto-completion cache.

```bash
USAGE
  $ gr4vy autocomplete [SHELL] [-r]

ARGUMENTS
  SHELL  (zsh|bash|powershell) Shell type

FLAGS
  -r, --refresh-cache  Refresh cache (ignores displaying instructions)

DESCRIPTION
  display autocomplete installation instructions

EXAMPLES
  $ gr4vy autocomplete

  $ gr4vy autocomplete bash

  $ gr4vy autocomplete zsh

  $ gr4vy autocomplete powershell

  $ gr4vy autocomplete --refresh-cache

```

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

### Create Checkout Session with Gr4vy SDK in PHP

Source: https://docs.mattildapayments.com/guides/payments/secure-fields/quick-start/sdks

This PHP code snippet demonstrates how to initialize the Gr4vy SDK, define cart items, buyer information, and create a checkout session. It requires the 'gr4vy/gr4vy-php' package and uses strict typing for better code quality. The output is a response object that can be used to handle the checkout session.

```php
declare(strict_types=1);

require 'vendor/autoload.php';

use Brick\DateTime\LocalDate;
use Gr4vy;
use Gr4vy\Utils;

$sdk = Gr4vy\SDK::builder()
    ->setMerchantAccountId('default')
    ->setSecurity(
        '<YOUR_BEARER_TOKEN_HERE>'
    )
    ->build();

$checkoutSessionCreate = new Gr4vy\CheckoutSessionCreate(
    cartItems: [
        new Gr4vy\CartItem(
            name: 'GoPro HD',
            quantity: 2,
            unitAmount: 1299,
            discountAmount: 0,
            taxAmount: 0,
            externalIdentifier: 'goprohd',
            sku: 'GPHD1078',
            productUrl: 'https://example.com/catalog/go-pro-hd',
            imageUrl: 'https://example.com/images/go-pro-hd.jpg',
            categories: [
                'camera',
                'travel',
                'gear',
            ],
            productType: 'physical',
            sellerCountry: 'US',
        ),
        new Gr4vy\CartItem(
            name: 'GoPro HD',
            quantity: 2,
            unitAmount: 1299,
            discountAmount: 0,
            taxAmount: 0,
            externalIdentifier: 'goprohd',
            sku: 'GPHD1078',
            productUrl: 'https://example.com/catalog/go-pro-hd',
            imageUrl: 'https://example.com/images/go-pro-hd.jpg',
            categories: [
                'camera',
                'travel',
                'gear',
            ],
            productType: 'physical',
            sellerCountry: 'US',
        ),
    ],
    metadata: [
        'cohort' => 'cohort-a',
        'order_id' => 'order-12345',
    ],
    buyer: new Gr4vy\GuestBuyerInput(
        displayName: 'John Doe',
        externalIdentifier: 'buyer-12345',
        billingDetails: new Gr4vy\BillingDetailsInput(
            firstName: 'John',
            lastName: 'Doe',
            emailAddress: 'john@example.com',
            phoneNumber: '+1234567890',
            address: new Gr4vy\Address(
                city: 'San Jose',
                country: 'US',
                postalCode: '94560',
                state: 'California',
                stateCode: 'US-CA',
                houseNumberOrName: '10',
                line1: 'Stafford Appartments',
                line2: '29th Street',
                organization: 'Gr4vy',
            ),
            taxId: new Gr4vy\TaxId(
                value: '12345678931',
                kind: 'my.frp',
            ),
        ),
        shippingDetails: new Gr4vy\ShippingDetailsCreate(
            firstName: 'John',
            lastName: 'Doe',
            emailAddress: 'john@example.com',
            phoneNumber: '+1234567890',
            address: null,
        ),
    ),
);

$response = $sdk->checkoutSessions->create(
    checkoutSessionCreate: $checkoutSessionCreate
);

if ($response->checkoutSession !== null) {
    // handle response
}

```

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

### Create Transaction Retries Report Specification

Source: https://docs.mattildapayments.com/guides/dashboard/reports/models-transaction-retries

This JSON example shows how to create a report specification for transaction retries. It defines the report name and the specification, including the model ('transaction_retries') and parameters. The 'params' object contains a 'filters' dictionary, here demonstrating a 'created_at' filter with a specific start date.

```json
{
  "name": "Test report",
  "spec": {
    "model": "transaction_retries",
    "params": {
      "filters": {
        "created_at": {
          "start": "2023-01-01T00:00:00"
        }
      }
    }
  }
}
```

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

### Fetch OpenAPI Specification File

Source: https://docs.mattildapayments.com/reference/payment-service-tokens/provision-payment-service-token

This example shows how to fetch the OpenAPI specification file for the API. The file, named 'llms.txt', is located at a specified URL and contains navigation and other documentation details.

```http
GET https://docs.mattildapayments.com/llms.txt
```

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

### Fetch Navigation and Other Pages

Source: https://docs.mattildapayments.com/reference/checkout-sessions/update-checkout-session-fields

Instructions on how to fetch navigation and other pages from the documentation.

```APIDOC
## Fetch Navigation and Other Pages

### Description
To find navigation and other pages within this documentation, you can fetch the `llms.txt` file from the provided URL.

### Method
GET

### Endpoint
https://docs.mattildapayments.com/llms.txt

### Parameters
N/A

### Request Example
```bash
curl https://docs.mattildapayments.com/llms.txt
```

### Response
#### Success Response (200)
- **content** (string) - The content of the llms.txt file, which may contain navigation links and other page information.

#### Response Example
```json
{
  "navigation": [
    {
      "title": "Home",
      "url": "/"
    },
    {
      "title": "API Reference",
      "url": "/api"
    }
  ],
  "pages": [
    {
      "title": "Getting Started",
      "url": "/getting-started"
    }
  ]
}
```
```

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

### Configure Gr4vy CLI with credentials

Source: https://docs.mattildapayments.com/guides/tools/cli

Initializes the Gr4vy CLI configuration by providing your Gr4vy ID, environment (sandbox or production), and the path to your private key. This command securely stores your credentials for future use in a configuration file (e.g., ~/.gr4vyrc.json).

```sh
gr4vy init acme sandbox private_key.pem
```

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

### Fetching Additional Documentation

Source: https://docs.mattildapayments.com/reference/transactions/get-refund

Instructions on how to fetch additional documentation files, such as navigation and other pages.

```APIDOC
## Additional Documentation

To find navigation and other pages in this documentation, fetch the `llms.txt` file at:

`https://docs.mattildapayments.com/llms.txt`
```

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

### Install Gr4vy React Native SDK using Yarn or npm

Source: https://docs.mattildapayments.com/guides/payments/react-native/quick-start/embed

Installs the Gr4vy React Native SDK and its native dependencies for iOS and Android. This enables storing card details, authorizing payments, and capturing transactions.

```sh
yarn add @gr4vy/embed-react-native
# OR
npm install @gr4vy/embed-react-native
```

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

### Create Checkout Session with Gr4vy SDK (Python)

Source: https://docs.mattildapayments.com/guides/payments/secure-fields/quick-start/sdks

This Python code snippet demonstrates how to create a checkout session using the Gr4vy SDK. It includes details for cart items, buyer information, and metadata. Ensure the Gr4vy SDK is installed and configured.

```python
from gr4vy.api import Gr4vy
from gr4vy.model.checkout_session_options import CheckoutSessionOptions
from gr4vy.model.cart_item_input import CartItemInput
from gr4vy.model.guest_buyer_input import GuestBuyerInput
from gr4vy.model.billing_details_input import BillingDetailsInput
from gr4vy.model.address import Address
from gr4vy.model.tax_id import TaxID
from gr4vy.model.shipping_details_create import ShippingDetailsCreate

# Assuming gr4vy is initialized elsewhere with your credentials
# gr4vy = Gr4vy(gr4vy_id='your_gr4vy_id', private_key='your_private_key')

checkout_session = gr4vy.checkout_sessions.create(
    options=CheckoutSessionOptions(
        amount=1000,
        currency='USD',
        country='US',
        cart_items=[
            CartItemInput(
                name='GoPro HD',
                quantity=2,
                unit_amount=1299,
                discount_amount=0,
                tax_amount=0,
                external_identifier="goprohd",
                sku="GPHD1078",
                product_url="https://example.com/catalog/go-pro-hd",
                image_url="https://example.com/images/go-pro-hd.jpg",
                categories=[
                    "camera",
                    "travel",
                    "gear",
                ],
                product_type="physical",
                seller_country="MX",
            ),
        ],
        metadata={
            "cohort": "cohort-a",
            "order_id": "order-12345",
        },
        buyer=GuestBuyerInput(
            display_name="John Doe",
            external_identifier="buyer-12345",
            billing_details=BillingDetailsInput(
                first_name="John",
                last_name="Doe",
                email_address="john@example.com",
                phone_number="+1234567890",
                address=Address(
                    city="San Jose",
                    country="MX",
                    postal_code="94560",
                    state="California",
                    state_code="US-CA",
                    house_number_or_name="10",
                    line1="Stafford Appartments",
                    line2="29th Street",
                    organization="Gr4vy",
                ),
                tax_id=TaxID(
                    value="12345678931",
                    kind="ar.cuit",
                ),
            ),
            shipping_details=ShippingDetailsCreate(
                first_name="John",
                last_name="Doe",
                email_address="john@example.com",
                phone_number="+1234567890",
                address=Address(
                    city="San Jose",
                    country="MX",
                    postal_code="94560",
                    state="California",
                    state_code="US-CA",
                    house_number_or_name="10",
                    line1="Stafford Appartments",
                    line2="29th Street",
                    organization="Gr4vy",
                ),
            ),
        ),
    )
)

# Handle response
print(checkout_session)
```

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

### Install Secure Fields React Library

Source: https://docs.mattildapayments.com/guides/payments/secure-fields/click-to-pay

Installs the Secure Fields React library using npm or yarn. This is the first step to integrating Secure Fields into a React application.

```bash
npm install @gr4vy/secure-fields-react --save
# or: yarn add @gr4vy/secure-fields-react
```

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

### Set Mattilda Payments Embed Environment to Sandbox

Source: https://docs.mattildapayments.com/guides/payments/embed/options

This example shows how to configure the Mattilda Payments Embed to use the sandbox environment instead of the default production environment. This is useful for testing payment integrations without processing live transactions.

```javascript
const embedConfig = {
  environment: "sandbox"
};
```

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

### Report Specification JSON Example

Source: https://docs.mattildapayments.com/guides/dashboard/reports/spec

An example of a report specification object in JSON format. This object defines the report model to be used and its associated parameters, including fields, filters, and sorting.

```json
{
  "model": "transactions",
  "params": {
    "fields": [ "id", "created_at"],
    "filters": {
      "status": ["capture_succeeded"]
    },
    "sort": [
      {
        "field": "created_at",
        "order": "desc"
      }
    ]
  }
}
```

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

### List Report Executions

Source: https://docs.mattildapayments.com/guides/dashboard/reports/how-to

Retrieve a list of all executions for a specific report. This is useful for tracking the status and history of report generation.

```APIDOC
## GET /reports/{report_id}/executions

### Description
Lists all executions for a given report.

### Method
GET

### Endpoint
/reports/{report_id}/executions

### Parameters
#### Path Parameters
- **report_id** (string) - Required - The ID of the report to list executions for.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of items to return.
- **cursor** (string) - Optional - A cursor for fetching the next page of results.

### Response
#### Success Response (200)
- **items** (array) - A list of report execution objects.
  - **type** (string) - The type of the object (e.g., "report-execution").
  - **id** (string) - The unique identifier for the execution.
  - **created_at** (string) - The timestamp when the execution was created.
  - **updated_at** (string) - The timestamp when the execution was last updated.
  - **status** (string) - The status of the execution.
  - **context** (object) - Contextual information for the execution.
  - **report** (object) - Information about the associated report.
- **limit** (integer) - The limit applied to the number of items returned.
- **next_cursor** (string|null) - A cursor for fetching the next page of results.
- **previous_cursor** (string|null) - A cursor for fetching the previous page of results.

#### Response Example
```json
{
  "items": [
    {
      "type": "report-execution",
      "id": "0848ef01-f44a-4564-abdb-52a1344bac63",
      "created_at": "2022-10-28T10:15:36.571232+00:00",
      "updated_at": "2022-10-28T10:15:36.611495+00:00",
      "status": "dispatched",
      "context": {
        "reference_timestamp": "2022-10-28T10:15:36.571232+00:00",
        "reference_timezone": "Etc/UTC"
      },
      "report": {
        "type": "report",
        "id": "71aa8d49-5ec7-43aa-b13c-9b16fdae0f9b",
        "name": "Successful captures"
      }
    }
  ],
  "limit": 20,
  "next_cursor": null,
  "previous_cursor": null
}
```
```

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

### POST /payment-options/list

Source: https://docs.mattildapayments.com/guides/payments/direct-api/quick-start/payment-options

Get a list of payment options that can be shown at checkout for a given set of transaction details. This endpoint is useful for dynamically displaying available payment methods to your customers.

```APIDOC
## POST /payment-options/list

### Description
Retrieves a list of available payment options based on transaction details such as amount, currency, country, cart items, and metadata. The API automatically applies checkout Flow rules to filter the results.

### Method
POST

### Endpoint
/payment-options/list

### Parameters
#### Query Parameters
- **locale** (string) - Optional - The locale to use for the payment options. Example: "en"

#### Request Body
- **amount** (integer) - Required - The transaction amount in the smallest currency unit.
- **currency** (string) - Required - The ISO currency code for the transaction.
- **country** (string) - Required - The ISO country code for the transaction.
- **cart_items** (array) - Optional - A list of items in the cart.
  - **name** (string) - Required - The name of the item.
  - **price** (integer) - Required - The price of the item in the smallest currency unit.
  - **quantity** (integer) - Required - The quantity of the item.
  - **sku** (string) - Optional - The Stock Keeping Unit for the item.
- **metadata** (object) - Optional - Custom data to be passed to the payment gateway.

### Request Example
```json
{
  "amount": 10000,
  "currency": "USD",
  "country": "US",
  "cart_items": [
    {
      "name": "Example Product",
      "price": 5000,
      "quantity": 2
    }
  ],
  "metadata": {
    "customer_id": "cust_123"
  }
}
```

### Response
#### Success Response (200)
- **items** (array) - A list of available payment options.
  - **type** (string) - The type of the payment option (e.g., "payment-option").
  - **method** (string) - The payment method identifier (e.g., "card", "paypal").
  - **icon_url** (string) - The URL for the payment method's icon.
  - **mode** (string) - The mode of the payment method (e.g., "card").
  - **label** (string) - A user-friendly label for the payment method.
  - **can_store_payment_method** (boolean) - Indicates if the payment method can be stored for future use.
  - **can_delay_capture** (boolean) - Indicates if the payment capture can be delayed.
  - **context** (object) - Additional context for the payment option.
    - **approval_ui** (object) - Information about the approval UI.
      - **height** (string) - The height of the approval UI.
      - **width** (string) - The width of the approval UI.
    - **required_fields** (object) - Any additional fields required for this payment option.

#### Response Example
```json
{
  "items": [
    {
      "type": "payment-option",
      "method": "card",
      "icon_url": "https://api.sandbox.mattildapayments.com/assets/icons/payment-methods/card.svg",
      "mode": "card",
      "label": "Card",
      "can_store_payment_method": true,
      "can_delay_capture": true,
      "context": {
        "approval_ui": {
          "height": "589px",
          "width": "500px"
        },
        "required_fields": {}
      }
    }
  ]
}
```
```

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

### Example of Buyer Search Query Parameter

Source: https://docs.mattildapayments.com/reference

Illustrates how to use the `buyer_search` parameter to filter transactions based on multiple buyer-related string values. This parameter accepts an array of strings.

```json
[
  "John",
  "London"
]
```

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

### Get Payment Options List (Python)

Source: https://docs.mattildapayments.com/guides/payments/direct-api/quick-start/payment-options

Initializes the Gr4vy Python client with production server and bearer token authentication to retrieve payment options. It then calls the payment_options.list method.

```python
from gr4vy import Gr4vy, auth
import os


with Gr4vy(
    id="mattilda",
    server="production",
    merchant_account_id="example",
    bearer_auth=auth.with_token(open("./private_key.pem").read())
) as g_client:

    res = g_client.payment_options.list(locale="en")

    # Handle response
    print(res)
```

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

### Get Payment Options List (C#)

Source: https://docs.mattildapayments.com/guides/payments/direct-api/quick-start/payment-options

Initializes the Gr4vy SDK and calls the ListAsync method to retrieve available payment options. Requires Gr4vy SDK and authentication details.

```csharp
using Gr4vy;
using Gr4vy.Models.Components;

var sdk = new Gr4vySDK(
    id: "mattilda",
    server: SDKConfig.Server.Sandbox,
    bearerAuthSource: Auth.WithToken(privateKey),
    merchantAccountId: "example"
);

var res = await sdk.PaymentOptions.ListAsync(paymentOptionRequest: new PaymentOptionRequest() {});

// handle response
```

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

### Create Checkout Session in Go

Source: https://docs.mattildapayments.com/guides/payments/secure-fields/quick-start/sdks

This Go code snippet demonstrates how to create a checkout session using the Gr4vy SDK. It defines cart items with product details, quantities, and pricing, along with metadata and buyer information. Error handling is included for the API call.

```go
package main

import (
	"log"

	"github.com/gr4vy/gr4vy-go/pkg/gr4vy/components"
	"github.com/gr4vy/gr4vy-go/pkg/gr4vy/gr4vygo"
)

func main() {
	// Assume gr4vygo.NewClient() is initialized and configured
	// Assume checkoutSession, err := gr4vygo.NewClient().CheckoutSessions().Create(
	// 	components.CheckoutSessionCreate{
	// 		CartItems: []components.CartItem{
	// 			components.CartItem{
	// 				Name: "GoPro HD",
	// 				Quantity: 2,
	// 				UnitAmount: 1299,
	// 				DiscountAmount: gr4vygo.Int64(0),
	// 				TaxAmount: gr4vygo.Int64(0),
	// 				ExternalIdentifier: gr4vygo.String("goprohd"),
	// 				Sku: gr4vygo.String("GPHD1078"),
	// 				ProductURL: gr4vygo.String("https://example.com/catalog/go-pro-hd"),
	// 				ImageURL: gr4vygo.String("https://example.com/images/go-pro-hd.jpg"),
	// 				Categories: []string{
	// 					"camera",
	// 					"travel",
	// 					"gear",
	// 				},
	// 				ProductType: components.ProductTypePhysical.ToPointer(),
	// 				SellerCountry: gr4vygo.String("MX"),
	// 			},
	// 			components.CartItem{
	// 				Name: "GoPro HD",
	// 				Quantity: 2,
	// 				UnitAmount: 1299,
	// 				DiscountAmount: gr4vygo.Int64(0),
	// 				TaxAmount: gr4vygo.Int64(0),
	// 				ExternalIdentifier: gr4vygo.String("goprohd"),
	// 				Sku: gr4vygo.String("GPHD1078"),
	// 				ProductURL: gr4vygo.String("https://example.com/catalog/go-pro-hd"),
	// 				ImageURL: gr4vygo.String("https://example.com/images/go-pro-hd.jpg"),
	// 				Categories: []string{
	// 					"camera",
	// 					"travel",
	// 					"gear",
	// 				},
	// 				ProductType: components.ProductTypePhysical.ToPointer(),
	// 				SellerCountry: gr4vygo.String("MX"),
	// 			}
	// 	},
	// 	Metadata: map[string]string{
	// 		"cohort": "cohort-a",
	// 		"order_id": "order-12345",
	// 	},
	// 	Buyer: nil,
	// })
	// if err != nil {
	// 	log.Fatal(err)
	// }
	// if checkoutSession != nil {
	// 	// handle response
	// }
}
```

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

### Configure Gr4vy CLI with Credentials

Source: https://docs.mattildapayments.com/guides/tools

After installation, configure the Gr4vy CLI with your Gr4vy ID, environment, and private key. This command securely stores your credentials, typically in a `~/.gr4vyrc.json` file, for subsequent use. The `private_key.pem` should be the path to your downloaded private key.

```bash
gr4vy init acme sandbox private_key.pem

```

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

### GET /websites/mattildapayments/buyers/{id}

Source: https://docs.mattildapayments.com/reference/buyers/get-buyer

Fetches a buyer by its ID. Requires 'buyers.read' scope. 'buyers.billing-details.read' scope is needed for PII.

```APIDOC
## GET /websites/mattildapayments/buyers/{id}

### Description
Fetches a buyer by its ID.

### Method
GET

### Endpoint
/websites/mattildapayments/buyers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the buyer.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the buyer.
- **first_name** (string) - The first name of the buyer.
- **last_name** (string) - The last name of the buyer.
- **email** (string) - The email address of the buyer.
- **phone_number** (string) - The phone number of the buyer.
- **billing_details** (object) - Contains billing information. Requires `buyers.billing-details.read` scope.
  - **address** (string) - The billing address.
  - **city** (string) - The billing city.
  - **state** (string) - The billing state.
  - **zip_code** (string) - The billing zip code.
  - **country** (string) - The billing country.

#### Response Example
```json
{
  "id": "buyer_123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone_number": "+1234567890",
  "billing_details": {
    "address": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip_code": "90210",
    "country": "USA"
  }
}
```
```

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

### Add gr4vy-ios SDK Dependency to Podfile

Source: https://docs.mattildapayments.com/guides/payments/ios/quick-start/ios

Specifies how to add the gr4vy-ios SDK as a dependency in your application's Podfile. This ensures the SDK is included in your project when you run 'pod install'. Replace 'TARGET_NAME' with your actual build target.

```ruby
use_frameworks!

target 'TARGET_NAME' do
    pod 'gr4vy-ios', '1.3.0'
end
```

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

### Initialize Gr4vy SDK Client

Source: https://docs.mattildapayments.com/guides/payments/secure-fields/click-to-pay

Initializes the Gr4vy SDK client using an instance ID and a private key. The private key should be securely stored and loaded, not exposed client-side. Supported languages include C#, Go, Java, PHP, Python, and TypeScript.

```csharp
using Gr4vy;
using Gr4vy.Models.Components;
using System.Collections.Generic;

// Loaded the key from a file, env variable, 
// or anywhere else
var privateKey = "..."; 

var sdk = new Gr4vySDK(
    id: "mattilda",
    server: SDKConfig.Server.Sandbox,
    bearerAuthSource: Auth.WithToken(privateKey),
    merchantAccountId: "example"
);

```

```go
package main

import (
	"context"
	gr4vy "github.com/gr4vy/gr4vy-go"
	"github.com/gr4vy/gr4vy-go/models/operations"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	privateKey := "...." // Private key loaded from disk or env var
	withToken := gr4vy.WithToken(privateKey, []JWTScope{ReadAll, WriteAll}, 60)

	s := gr4vy.New(
		gr4vy.WithID("mattilda"),
		gr4vy.WithServer(gr4vy.ServerSandbox),
		gr4vy.WithSecuritySource(withToken),
		gr4vy.WithMerchantAccountID("example"),
	)
}

```

```java
package hello.world;

import com.gr4vy.sdk.BearerSecuritySource;
import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.Gr4vy.AvailableServers;
import com.gr4vy.sdk.models.components.AccountUpdaterJobCreate;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.ListTransactionsRequest;
import java.lang.Exception;
import java.util.List;

public class Application {

    public static void main(String[] args) throws Exception {

        String privateKey = "-----\n...."; // a valid private key

        Gr4vy sdk = Gr4vy.builder()
                .id("mattilda")
                .server(AvailableServers.SANDBOX)
                .merchantAccountId("example")
                .securitySource(new BearerSecuritySource.Builder(privateKey).build())
            .build();
    }
}

```

```php
declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;
use Gr4vy\Auth;

// Loaded the key from a file, env variable, 
// or anywhere else
$privateKey = "..."; 

$sdk = Gr4vy\SDK::builder()
    ->setId('mattilda')
    ->setServer('sandbox')
    ->setSecuritySource(Auth::withToken($privateKey))
    ->setMerchantAccountId('mattilda')
    ->build();

```

```python
from gr4vy import Gr4vy, auth
import os

client = Gr4vy(
    id="mattilda",
    server="production",
    merchant_account_id="example",
    bearer_auth=auth.with_token(open("./private_key.pem").read())
)

```

```typescript
import fs from "fs";
import { Gr4vy, withToken } from "@gr4vy/sdk";

const gr4vy = new Gr4vy({
    server: "sandbox",
    id: "mattilda",
    bearerAuth: withToken({
      privateKey: fs.readFileSync("private_key.pem", "utf8"),
    }),
});

```

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

### Get Payment Options List (PHP)

Source: https://docs.mattildapayments.com/guides/payments/direct-api/quick-start/payment-options

Configures the Gr4vy PHP SDK with sandbox server and token authentication to fetch available payment methods. It instantiates a PaymentOptionRequest and calls the list method.

```php
declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;
use Gr4vy\Auth;

, 
$privateKey = "..."; 

$sdk = Gr4vy\SDK::builder()
    ->setId('mattilda')
    ->setServer('sandbox')
    ->setSecuritySource(Auth::withToken($privateKey))
    ->setMerchantAccountId('example')
    ->build();

$paymentOptionRequest = new Gr4vy\PaymentOptionRequest();

$response = $sdk->paymentOptions->list(
    paymentOptionRequest: $paymentOptionRequest
);

if ($response->paymentOptions !== null) {
    // handle response
}
```
Tokens:
Raw