PSP Tokenization

PSP tokenization provisions a card stored in the Gr4vy vault as a token on a specific payment provider (PSP). The provider issues its own token that references the card on their side. This token is the provider’s reusable reference to the stored card, not a single-use token. PSP tokens are used when a downstream service requires a provider-specific reference rather than raw card data — for example, when migrating recurring mandates or storing a card on a provider for future use.

PSP tokens vs network tokens

	PSP token	Network token
Issued by	Payment provider (PSP/acquirer)	Card scheme (Visa, Mastercard)
Portability	Tied to one provider	Can work across supported providers
Use case	Provider-specific integrations	Authorization rate optimization, recurring payments

For most use cases, network tokens are preferred because they can be more portable across supported providers and provide higher authorization rates. PSP tokens are useful when a specific provider requires its own token format.

Provisioning a PSP token

To provision a PSP token, the card must already be stored in the Gr4vy vault as a payment method. Call the provision endpoint with the target payment service ID.

using Gr4vy;
using Gr4vy.Models.Components;

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

var res = await sdk.PaymentMethods.PaymentServiceTokens.CreateAsync(
    paymentMethodId: "ef9496d8-53a5-4aad-8ca2-00eb68334389",
    paymentServiceTokenCreate: new PaymentServiceTokenCreate() {
        PaymentServiceId = "fffd152a-9532-4087-9a4f-de58754210f0",
        RedirectUrl = "https://example.com/callback",
    }
);

// handle response

package main

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

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

    s := gr4vygo.New(
        gr4vygo.WithMerchantAccountID("default"),
        gr4vygo.WithSecurity(os.Getenv("GR4VY_BEARER_AUTH")),
    )

    res, err := s.PaymentMethods.PaymentServiceTokens.Create(
        ctx,
        "ef9496d8-53a5-4aad-8ca2-00eb68334389",
        components.PaymentServiceTokenCreate{
            PaymentServiceID: "fffd152a-9532-4087-9a4f-de58754210f0",
            RedirectURL:      "https://example.com/callback",
        },
    )
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        // handle response
    }
}

package hello.world;

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.components.PaymentServiceTokenCreate;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.CreatePaymentMethodPaymentServiceTokenResponse;
import java.lang.Exception;

public class Application {

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

        Gr4vy sdk = Gr4vy.builder()
                .merchantAccountId("default")
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        CreatePaymentMethodPaymentServiceTokenResponse res = sdk.paymentMethods().paymentServiceTokens().create()
                .paymentMethodId("ef9496d8-53a5-4aad-8ca2-00eb68334389")
                .paymentServiceTokenCreate(PaymentServiceTokenCreate.builder()
                    .paymentServiceId("fffd152a-9532-4087-9a4f-de58754210f0")
                    .redirectUrl("https://example.com/callback")
                    .build())
                .call();

        if (res.paymentServiceToken().isPresent()) {
            System.out.println(res.paymentServiceToken().get());
        }
    }
}

declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;
use Gr4vy\Auth;

$privateKey = file_get_contents('./private_key.pem');

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

$response = $sdk->paymentMethods->paymentServiceTokens->create(
    paymentMethodId: 'ef9496d8-53a5-4aad-8ca2-00eb68334389',
    paymentServiceTokenCreate: new Gr4vy\PaymentServiceTokenCreate(
        paymentServiceId: 'fffd152a-9532-4087-9a4f-de58754210f0',
        redirectUrl: 'https://example.com/callback',
    )
);

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

from gr4vy import Gr4vy, auth

with Gr4vy(
    id="example",
    server="sandbox",
    merchant_account_id="default",
    bearer_auth=auth.with_token(open("./private_key.pem").read())
) as g_client:
    res = g_client.payment_methods.payment_service_tokens.create(
        payment_method_id="ef9496d8-53a5-4aad-8ca2-00eb68334389",
        payment_service_id="fffd152a-9532-4087-9a4f-de58754210f0",
        redirect_url="https://example.com/callback"
    )
    print(res)

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

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

const result = await gr4vy.paymentMethods.paymentServiceTokens.create({
    paymentServiceId: "fffd152a-9532-4087-9a4f-de58754210f0",
    redirectUrl: "https://example.com/callback",
}, "ef9496d8-53a5-4aad-8ca2-00eb68334389");

console.log(result);

The response contains the provisioned token details, including the provider’s token reference.

Listing PSP tokens

To retrieve existing PSP tokens for a payment method:

using Gr4vy;

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

var res = await sdk.PaymentMethods.PaymentServiceTokens.ListAsync(
    paymentMethodId: "ef9496d8-53a5-4aad-8ca2-00eb68334389"
);

// handle response

package main

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

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

    s := gr4vygo.New(
        gr4vygo.WithMerchantAccountID("default"),
        gr4vygo.WithSecurity(os.Getenv("GR4VY_BEARER_AUTH")),
    )

    res, err := s.PaymentMethods.PaymentServiceTokens.List(
        ctx,
        "ef9496d8-53a5-4aad-8ca2-00eb68334389",
    )
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        // handle response
    }
}

package hello.world;

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.operations.ListPaymentMethodPaymentServiceTokensResponse;
import java.lang.Exception;

public class Application {

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

        Gr4vy sdk = Gr4vy.builder()
                .merchantAccountId("default")
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        ListPaymentMethodPaymentServiceTokensResponse res = sdk.paymentMethods().paymentServiceTokens().list()
                .paymentMethodId("ef9496d8-53a5-4aad-8ca2-00eb68334389")
                .call();

        if (res.paymentServiceTokens().isPresent()) {
            System.out.println(res.paymentServiceTokens().get());
        }
    }
}

declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;
use Gr4vy\Auth;

$privateKey = file_get_contents('./private_key.pem');

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

$response = $sdk->paymentMethods->paymentServiceTokens->list(
    paymentMethodId: 'ef9496d8-53a5-4aad-8ca2-00eb68334389'
);

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

from gr4vy import Gr4vy, auth

with Gr4vy(
    id="example",
    server="sandbox",
    merchant_account_id="default",
    bearer_auth=auth.with_token(open("./private_key.pem").read())
) as g_client:
    res = g_client.payment_methods.payment_service_tokens.list(
        payment_method_id="ef9496d8-53a5-4aad-8ca2-00eb68334389"
    )
    print(res)

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

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

const result = await gr4vy.paymentMethods.paymentServiceTokens.list(
    "ef9496d8-53a5-4aad-8ca2-00eb68334389"
);

console.log(result);

Deleting a PSP token

When you delete a PSP token, Gr4vy removes it from the payment method. For connectors that support deleting tokens, Gr4vy also asks the provider to delete its stored copy. If the provider declines that request, the API returns an error and Gr4vy keeps the token. For other connectors, Gr4vy removes the token only on its side, and the stored card stays with the provider. Connectors that support it list Delete token in the Capabilities section of their connection page. You can delete PSP tokens for card payment methods only.

API reference

Provision PSP token

POST /payment-methods/payment_method_id/payment-service-tokens

List PSP tokens

GET /payment-methods/payment_method_id/payment-service-tokens

Delete PSP token

DELETE /payment-methods/payment_method_id/payment-service-tokens/payment_service_token_id

Get started

Integration guides

Best Practices

Resources

Features

Other

PSP Tokenization

PSP tokens vs network tokens

Provisioning a PSP token

Listing PSP tokens

Deleting a PSP token

API reference

Provision PSP token

List PSP tokens

Delete PSP token

​PSP tokens vs network tokens

​Provisioning a PSP token

​Listing PSP tokens

​Deleting a PSP token

​API reference

Provision PSP token

List PSP tokens

Delete PSP token

PSP tokens vs network tokens

Provisioning a PSP token

Listing PSP tokens

Deleting a PSP token

API reference