Create a merchant token

/v0.1/merchants/{merchant_code}/tokens

Creates a short-lived token for the merchant account identified by merchant_code and the requested actions.

Call this endpoint from your backend using a supported authentication method. You must have access to the merchant account. Before returning the token, check that the user signed in to your application is allowed to accept payments for that account.

Pass the returned access_token to the SDK. The token expires 15 minutes after creation; use expires_in for its remaining lifetime. To continue after it expires, create a new token through this endpoint.

Required permissions:

{"relation":"tokens.create","object_type":"merchant","object_id_param":"merchant_code"}

Authorization

Use one of the following alternatives:

apiKey
oauth2

Authorization guide

Path parameters

merchant_codestringrequired
Unique code of the merchant account that will receive the payments.

Example: "MC0X0ABC"

Body parameters

application/jsonrequired

Actions the merchant token should allow.

actionsarray<string>required
Options:"checkout"
Actions the token allows for this merchant account.

Example: ["checkout"]

Responses

200application/json

Merchant token created. Pass its access_token to the SDK.

access_tokenstringrequired
Secret token to pass to the SDK. Treat this value as an opaque string; do not parse it or depend on its format.

Example: "MERCHANT_TOKEN"
token_typestringrequired
Options:"Bearer"
Authentication scheme used by the token. Always Bearer.

Example: "Bearer"
expires_inintegerrequired
minimum: 0
Remaining lifetime of the token in seconds when the response is created. Tokens expire 15 minutes after creation. Request a new token when needed.

Example: 899

400application/problem+json

The request body is invalid or contains unsupported or duplicate actions.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

401application/json

Authentication is missing, invalid, or expired.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

application/problem+json

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

{
  "type": "https://developer.sumup.com/problem/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Token is invalid or expired."
}

403application/json

The authenticated identity does not have permission to create tokens for this merchant account.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

Code sample

curl --request POST \
  --url https://api.sumup.com/v0.1/merchants/MC0X0ABC/tokens \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "actions": [
    "checkout"
  ]
}
'

import SumUp from "@sumup/sdk";

async function main() {
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });

  const result = await client.tokens.create(
    "MC0X0ABC",
    {
      "actions": [
        "checkout"
      ]
    }
  );
  console.log(result);
}

main().catch(console.error);

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SumUp;

public static class Program
{
    public static async Task Main()
    {
        using var client = new SumUpClient();
        var response = await client.Tokens.CreateAsync(
            "your-merchant-code",
            new TokensCreateRequest
            {
                Actions = new TokensCreateRequestActionsItem[]
                {
                    TokensCreateRequestActionsItem.Checkout,
                },
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

public final class CreateMerchantTokenSample {
  public static void main(String[] args) throws Exception {
    var client = new SumUpClient();

    var result = client.tokens().create(
            "MC0X0ABC",
            com.sumup.sdk.models.CreateMerchantTokenRequest.builder()
                .actions(java.util.List.of(com.sumup.sdk.models.CreateMerchantTokenRequestActionsItem.of("checkout")))
                .build()
        );
    System.out.println(result);
  }
}

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$sumup = new \SumUp\SumUp('sup_sk_your_api_key');

$body = [
    'actions' => [
        'checkout',
    ],
];

$result = $sumup->tokens()->create(
    'MC0X0ABC',
    $body,
);

var_dump($result);

package main

import (
	"context"
	"fmt"

	"github.com/sumup/sumup-go"
)

func main() {
	client := sumup.NewClient()
	result, err := client.Tokens.Create(context.TODO(), "MC0X0ABC", sumup.TokensCreateParams{
		Actions: []sumup.TokensCreateParamsAction{"checkout"},
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", result)
}

use sumup::{Authorization, Client};
#[tokio::main]
async fn main() {
    let client = Client::default()
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
    let body = sumup::resources::tokens::CreateRequest::builder()
        .actions(vec![sumup::resources::tokens::CreateRequestActionsItem::Checkout])
        .build();
    let response = client
        .tokens()
        .create("MERCHANT_CODE", body)
        .await
        .expect("create request failed");
    println!("{response:#?}");
}

Response example

{
  "access_token": "MERCHANT_TOKEN",
  "token_type": "Bearer",
  "expires_in": 899
}

{
  "type": "https://developer.sumup.com/problem/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request contains an unsupported action."
}

{
  "type": "https://developer.sumup.com/problem/unauthorized",
  "title": "Unauthorized",
  "status": 401
}

{
  "type": "https://developer.sumup.com/problem/forbidden",
  "title": "Forbidden",
  "status": 403
}