> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Generate Tap to Pay activation code

POST https://api-sandbox.payabli.com/api/v2/device/taptopay/activate/challenge
Content-Type: application/json

Issues a short-lived activation code for a Tap to Pay device in the
`Pending` state. This endpoint is for Tap to Pay devices only.
Deliver the code to the device to complete activation.

A code is valid for 30 minutes after it's issued. Calling this
endpoint again for the same device before the code expires returns
the same code, with `alreadyIssued` set to `true`, instead of
generating a new one. A new code is only generated when no valid
code exists.

Authenticate with an OAuth2 bearer token that has the `pos_create`
permission. See [Accept Tap to Pay payments](/guides/pay-in-developer-tap-to-pay)
for the full integration guide.


Reference: https://docs.payabli.com/developers/api-reference/device/activation-challenge

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://api-sandbox.payabli.com/api` (Sandbox, default)
- `https://api.payabli.com/api` (Production)

## Request

### Body (application/json)

This endpoint expects an object.

- `entry` (string, required) — The entity's entrypoint identifier. [Learn more](/developers/api-reference/api-overview#entrypoint-vs-entry).
- `deviceId` (string, required) — The device identifier (`poiId`) returned when the device was registered.

## Response

### 200

Success

- `responseText` (string, required) — Response text for operation: 'Success' or 'Declined'.
- `responseData` (object, required) — The issued activation code, its expiration, and whether it was reused.
  - `code` (string, required) — The 6-digit activation code the partner delivers to the device user to activate the device. It can start with leading zeros, so keep it as a string.
  - `expiresAt` (datetime, required) — UTC time when the code expires, in ISO 8601 round-trip format. A code is valid for 30 minutes after it's issued.
  - `alreadyIssued` (boolean, required) — `true` when an unexpired code already exists for the device and this call returns it unchanged instead of generating a new one.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `pageIdentifier` (string, optional) — Auxiliary validation used internally by payment pages and components.
- `roomId` (long, optional) — Field not in use on this endpoint. It always returns `0`.
- `isSuccess` (boolean, optional) — Boolean indicating whether the operation was successful. A `true` value indicates success. A `false` value indicates failure.

## Errors

### 400 Bad Request Error

Bad request. Returned when `entry` or `deviceId` is missing from the request body.

- `isSuccess` (boolean, required) — Boolean indicating whether the operation was successful. A `true` value indicates success. A `false` value indicates failure.
- `responseText` (string, required) — Response text for operation: 'Success' or 'Declined'.
- `responseData` (object, required)
  - `resultCode` (integer, required) — The same status code as the HTTP response.
  - `resultText` (string, required) — A message describing why the request was refused.

### 401 Unauthorized Error

Unauthorized request.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (object, optional) — Object with detailed error context.
  - `explanation` (string, optional) — Human-readable explanation of what happened.
  - `todoAction` (string, optional) — Suggested resolution.

### 403 Forbidden Error

Forbidden. Returned when the token isn't authorized for `entry`, or when the device isn't in a state that allows activation (for example, it's already active).

- `isSuccess` (boolean, required) — Boolean indicating whether the operation was successful. A `true` value indicates success. A `false` value indicates failure.
- `responseText` (string, required) — Response text for operation: 'Success' or 'Declined'.
- `responseData` (object, required)
  - `resultCode` (integer, required) — The same status code as the HTTP response.
  - `resultText` (string, required) — A message describing why the request was refused.

### 404 Not Found Error

Returned when `deviceId` doesn't match a registered device on `entry`.

- `isSuccess` (boolean, required) — Boolean indicating whether the operation was successful. A `true` value indicates success. A `false` value indicates failure.
- `responseText` (string, required) — Response text for operation: 'Success' or 'Declined'.
- `responseData` (object, required)
  - `resultCode` (integer, required) — The same status code as the HTTP response.
  - `resultText` (string, required) — A message describing why the request was refused.

### 500 Internal Server Error

Internal server error.

- `isSuccess` (boolean, required) — Boolean indicating whether the operation was successful. A `true` value indicates success. A `false` value indicates failure.
- `responseText` (string, required) — Response text for operation: 'Success' or 'Declined'.
- `responseData` (object, required)
  - `resultCode` (integer, required) — The same status code as the HTTP response.
  - `resultText` (string, required) — A message describing why the request was refused.

## Examples

**Request**

```json
{
  "entry": "8cfec329267",
  "deviceId": "499585-389fj484-3jcj8hj3"
}
```

**Response**

```json
{
  "responseText": "Success",
  "responseData": {
    "code": "748801",
    "expiresAt": "2026-09-10T20:28:27.5860203Z",
    "alreadyIssued": false
  },
  "isSuccess": true
}
```

**SDK Code**

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        clientId: "YOUR_CLIENT_ID",
        clientSecret: "YOUR_CLIENT_SECRET",
    });
    await client.taptopay.activationChallenge({
        entry: "8cfec329267",
        deviceId: "499585-389fj484-3jcj8hj3",
    });
}
main();

```

```python
from payabli import payabli

client = payabli(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

client.taptopay.activation_challenge(
    entry="8cfec329267",
    device_id="499585-389fj484-3jcj8hj3",
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;
import io.github.payabli.api.resources.taptopay.requests.TapToPayActivationChallengeRequest;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient.withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
            .build()
        ;

        client.taptopay().activationChallenge(
            TapToPayActivationChallengeRequest
                .builder()
                .entry("8cfec329267")
                .deviceId("499585-389fj484-3jcj8hj3")
                .build()
        );
    }
}
```

```csharp
using PayabliApi;
using System.Threading.Tasks;

public partial class Examples
{
    public async Task Example() {
        var client = new PayabliApiClient(
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        );

        await client.Taptopay.ActivationChallengeAsync(
            new TapToPayActivationChallengeRequest {
                Entry = "8cfec329267",
                DeviceId = "499585-389fj484-3jcj8hj3"
            }
        );
    }

}

```

```go
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithClientCredentials(
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    request := &payabli.TapToPayActivationChallengeRequest{
        Entry: "8cfec329267",
        DeviceId: "499585-389fj484-3jcj8hj3",
    }
    client.Taptopay.ActivationChallenge(
        context.TODO(),
        request,
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\Taptopay\Requests\TapToPayActivationChallengeRequest;

$client = new PayabliClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
);
$client->taptopay->activationChallenge(
    new TapToPayActivationChallengeRequest([
        'entry' => '8cfec329267',
        'deviceId' => '499585-389fj484-3jcj8hj3',
    ]),
);

```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.payabli.com/api/v2/device/taptopay/activate/challenge")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entry\": \"8cfec329267\",\n  \"deviceId\": \"499585-389fj484-3jcj8hj3\"\n}"

response = http.request(request)
puts response.read_body
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "entry": "8cfec329267",
  "deviceId": "499585-389fj484-3jcj8hj3"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/device/taptopay/activate/challenge")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```