> ## 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.

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>

## 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>