Skip to main content
The API uses Bearer (Token) Authentication to authenticate requests. The value of this bearer token is a JSON Web Token (JWT), which is passed in the Authorization HTTP header and signed by your private API Key. 
curl -X GET https://api.mattildapayments.com/transactions \
  -H "authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIi..."

​
Create a new API key

To use the API you will need to generate a new API key. Head over to your dashboard and visit the Integrations page. API key dashboard On this page, click the Add API key button and select a name for your key. The name is purely for you to track what key is for what integration. You will need to store the downloaded key securely as we will not store this key for you.
Using an SDK is the most simple way to call and authenticate with our API. When using one of our SDKs to call the API, authentication is handled by the SDK client. You will only need to initialize the SDK with your private to handle authentication.

​
Install a server-side SDK

Use the package manager in your preferred programming language to install our server-side SDK. Token generation can only be done server side and we do not recommend doing this client side as it will expose your API key to your customers.
dotnet add package Gr4vy

go get github.com/gr4vy/gr4vy-go

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

composer require "gr4vy/gr4vy-php"

pip install gr4vy

npm install @gr4vy/sdk
# or: yarn add @gr4vy/sdk
Please always check and install the latest release of your preferred SDK.

​
Initialize the SDK client

Next, initialize the SDK with the ID of your instance and the private key.
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"
);

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"),
	)
}

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 = "-----BEGIN PRIVATE KEY-----\n...."; // a valid private key

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

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('example')
    ->build();

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())
)

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"),
    }),
});

​
Summary

In this step you:
  • Learned about API authentication
  • Created a new private key for the API
  • Used an SDK to authenticate or manually created a token