KartaPay

https://docs.kartapay.me/
Admin
KartaPay is a payment gateway that allows merchants to accept customer payments through local...
Tokens:6,568
Snippets:58
Trust Score:6.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Requête curl pour créer un paiement

Source: https://docs.kartapay.me/developer-guide/guides/create-a-payment

Envoyez une requête POST à /v1/payments avec un jeton d'accès Bearer et les données de paiement (purchase, clientId, cancelUrl, successUrl).

```bash
curl --request POST \
  --url https://api-staging.kartapay.me/v1/payments \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAi...' \
  --header 'Content-Type: application/json' \
  --data '{
    "purchase": {
      "total": {
        "value": "1475",
        "currency": "KMF"
      }
    },
    "clientId": "de627e0d87fd2bdcdd7bf72b2c436379",
    "cancelUrl": "https://merchant.com/checkout/cancel",
    "successUrl": "https://merchant.com/checkout/success"
  }'
```

--------------------------------

### Réponse de création de paiement

Source: https://docs.kartapay.me/developer-guide/guides/create-a-payment

Réponse JSON de l'API après création d'un paiement. Contient l'URL de redirection (next), l'identifiant du paiement, le statut 'pending', et le submitUrl dans data.billing.

```json
{
  "next": "https://checkout-staging.kartapay.me/payment/submit/67928bcc4c9deaf5696a0942",
  "data": {
    "id": "67928bcc4c9deaf5696a0942",
    "status": "pending",
    "captured": false,
    "purchase": {
      "total": {
        "value": "1475",
        "currency": "KMF"
      }
    },
    "cancelUrl": "https://merchant.com/checkout/cancel",
    "successUrl": "https://merchant.com/checkout/success",
    "billing": {
      "submitUrl": "https://checkout-staging.kartapay.me/payment/submit/67928bcc4c9deaf5696a0942"
    },
    "createdAt": "2025-01-23T15:51:08.625Z"
  }
}
```

--------------------------------

### En-têtes requis pour toutes les requêtes API

Source: https://docs.kartapay.me/developer-guide/getting-started/environments

Toutes les requêtes API doivent inclure ces en-têtes : Accept, Authorization avec un jeton d'accès, et Content-Type. Utilisez-les pour interagir avec les environnements de production ou de staging.

```http
Accept: application/json  

Authorization: Bearer <access_token>  

Content-Type: application/json  

```

--------------------------------

### Exemple de chaîne de message

Source: https://docs.kartapay.me/developer-guide/guides/verify-webhook-signatures

Exemple concret de chaîne de message avec des valeurs d'exemple pour chaque champ.

```text
67928bcc4c9deaf5696a0942,f66d217e-22be-4e8c-a461-bcf9a355190a,de627e0d87fd2bdcdd7bf72b2c436379,1475,KMF,2025-01-23T18:34:58.846Z,completed
```

--------------------------------

### Request an access token with curl

Source: https://docs.kartapay.me/developer-guide/getting-started/authentication

Use this curl command to request an OAuth2 access token from the KartaPay staging token endpoint. Replace 'xxx' with your actual Client ID and Client Secret. The grant type is 'client_credentials'.

```bash
curl --location 'https://auth.kartapay.me/staging/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=xxx' \
  --data-urlencode 'client_secret=xxx' \
  --data-urlencode 'grant_type=client_credentials'
```

--------------------------------

### POST https://auth.kartapay.me/staging/token

Source: https://docs.kartapay.me/developer-guide/getting-started/authentication

Requests an access token using the OAuth2 client_credentials grant type. Provide your Client ID and Client Secret as form-urlencoded parameters.

```APIDOC
## POST https://auth.kartapay.me/staging/token

### Description
Requests an access token using the OAuth2 client_credentials grant type. Provide your Client ID and Client Secret as form-urlencoded parameters.

### Method
POST

### Endpoint
https://auth.kartapay.me/staging/token

### Parameters
#### Request Body (application/x-www-form-urlencoded)
- **client_id** (string) - Required - Your Client ID obtained from the KartaPay dashboard.
- **client_secret** (string) - Required - Your Client Secret obtained from the KartaPay dashboard.
- **grant_type** (string) - Required - Must be `client_credentials`.

### Request Example
```
curl --location 'https://auth.kartapay.me/staging/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=xxx' \
  --data-urlencode 'client_secret=xxx' \
  --data-urlencode 'grant_type=client_credentials'
```

### Response
#### Success Response (200)
- **access_token** (string) - The JWT access token to be used as a Bearer token.
- **expires_in** (integer) - Token lifetime in seconds (3600).
- **refresh_expires_in** (integer) - Refresh token lifetime (always 0, no refresh token).
- **token_type** (string) - Token type (Bearer).
- **not-before-policy** (integer) - Not-before policy timestamp.
- **scope** (string) - Scope of the token (merchant-api-jwt-scope).

#### Response Example
```
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ...",
  "expires_in": 3600,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "merchant-api-jwt-scope"
}
```

### Notes
- The token expires after 1 hour (`expires_in: 3600`). Request a new token when it expires; there is no refresh token (`refresh_expires_in` is always 0).
- Use the `access_token` as a Bearer token in the `Authorization` header of each request to the KartaPay API.
```

--------------------------------

### Payload JSON de webhook pour payment.completed

Source: https://docs.kartapay.me/developer-guide/guides/receive-webhooks

Exemple de corps de notification JSON envoyé par KartaPay pour un événement de paiement terminé. Contient les détails du paiement, y compris le statut, le montant, la devise et les identifiants.

```json
{  

  "topic": "payment.completed",  

  "timestamp": "2025-01-23T18:37:17.115Z",  

  "type": "payment",  

  "data": {  

    "id": "67928bcc4c9deaf5696a0942",  

    "status": "completed",  

    "captured": true,  

    "total": {  

      "value": "1475",  

      "currency": "KMF"  

    },  

    "submittedAt": "2025-01-23T18:34:58.846Z",  

    "clientId": "de627e0d87fd2bdcdd7bf72b2c436379",  

    "providerId": "053A4F9526",  

    "source": "MVK"  

  }  

}  

```

--------------------------------

### Requête HTTP POST de webhook avec en-tête KartaPay-Signature

Source: https://docs.kartapay.me/developer-guide/guides/receive-webhooks

Exemple de requête HTTP POST envoyée par KartaPay à votre point de terminaison public. L'en-tête KartaPay-Signature contient la signature à vérifier pour authentifier le webhook.

```http
HTTP POST https://merchant.com/api/notifications  

KartaPay-Signature: 022dec5b0a7ad7135dfe3a14b3dd52f3961e3f1341628fded401d178ac41101b  

```

--------------------------------

### Exemple de corps d'erreur JSON (format RFC 7807)

Source: https://docs.kartapay.me/developer-guide/errors-and-idempotency

Exemple illustratif du corps d'erreur renvoyé par l'API en cas de validation. Les champs exacts peuvent varier ; fiez-vous au code de statut HTTP pour le contrôle de flux.

```json
{
  "type": "https://api.kartapay.me/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "purchase.total.value must be a positive integer string"
}
```

--------------------------------

### Construire la chaîne de message (champs séparés par des virgules)

Source: https://docs.kartapay.me/developer-guide/guides/verify-webhook-signatures

Liste des champs à concaténer dans l'ordre exact pour former la chaîne de message signée. Seuls ces sept champs sont couverts par la signature.

```text
id,merchantId,clientId,value,currency,submittedAt,status
```

--------------------------------

### Calculer HMAC-SHA256 en Node.js

Source: https://docs.kartapay.me/developer-guide/guides/verify-webhook-signatures

Génère un HMAC-SHA256 de la chaîne de message en utilisant le secret de webhook. Le secret doit être conservé en sécurité.

```javascript
const crypto = require('crypto');

const secretKey = 'secret_key'; // depuis votre tableau de bord KartaPay
const message = '67928bcc4c9deaf5696a0942,f66d217e-22be-4e8c-a461-bcf9a355190a,de627e0d87fd2bdcdd7bf72b2c436379,1475,KMF,2025-01-23T18:34:58.846Z,completed';

const hmacResult = crypto
  .createHmac('sha256', secretKey)
  .update(message)
  .digest('hex');

console.log('HMAC-SHA256:', hmacResult);
```

--------------------------------

### Calculer HMAC-SHA256 en Python

Source: https://docs.kartapay.me/developer-guide/guides/verify-webhook-signatures

Génère un HMAC-SHA256 de la chaîne de message en utilisant le secret de webhook. Le secret doit être conservé en sécurité.

```python
import hmac
import hashlib

secret_key = b'secret_key'  # depuis votre tableau de bord KartaPay
message = b'67928bcc4c9deaf5696a0942,f66d217e-22be-4e8c-a461-bcf9a355190a,de627e0d87fd2bdcdd7bf72b2c436379,1475,KMF,2025-01-23T18:34:58.846Z,completed'

hmac_result = hmac.new(secret_key, message, hashlib.sha256).hexdigest()
print("HMAC-SHA256:", hmac_result)
```

--------------------------------

### Token response JSON

Source: https://docs.kartapay.me/developer-guide/getting-started/authentication

The response from the token endpoint contains the access_token, which expires after 1 hour (expires_in: 3600). There is no refresh token (refresh_expires_in is always 0). Use the access_token as a Bearer token in the Authorization header for each API request.

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ...",
  "expires_in": 3600,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "merchant-api-jwt-scope"
}
```
Tokens:
Raw