> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/features/network-tokens/overview) 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.

<CodeGroup>
  ```csharp C# theme={"system"}
  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
  ```

  ```go Go theme={"system"}
  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
      }
  }
  ```

  ```java Java theme={"system"}
  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());
          }
      }
  }
  ```

  ```php PHP theme={"system"}
  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
  }
  ```

  ```python Python theme={"system"}
  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)
  ```

  ```ts TypeScript theme={"system"}
  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);
  ```
</CodeGroup>

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:

<CodeGroup>
  ```csharp C# theme={"system"}
  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
  ```

  ```go Go theme={"system"}
  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
      }
  }
  ```

  ```java Java theme={"system"}
  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());
          }
      }
  }
  ```

  ```php PHP theme={"system"}
  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
  }
  ```

  ```python Python theme={"system"}
  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)
  ```

  ```ts TypeScript theme={"system"}
  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);
  ```
</CodeGroup>

## Deleting a PSP token

When you [delete a PSP token](/reference/payment-service-tokens/delete-payment-service-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

<CardGroup cols={2}>
  <Card title="Provision PSP token" icon="code" href="/reference/payment-service-tokens/provision-payment-service-token">
    POST /payment-methods/{'{'}payment\_method\_id{'}'}/payment-service-tokens
  </Card>

  <Card title="List PSP tokens" icon="code" href="/reference/payment-service-tokens/list-payment-service-tokens">
    GET /payment-methods/{'{'}payment\_method\_id{'}'}/payment-service-tokens
  </Card>

  <Card title="Delete PSP token" icon="code" href="/reference/payment-service-tokens/delete-payment-service-token">
    DELETE /payment-methods/{'{'}payment\_method\_id{'}'}/payment-service-tokens/{'{'}payment\_service\_token\_id{'}'}
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.