Skip to main content
Version: 3.2

API: Technical information

OpenAPI specification​

The whole API is described by an OpenAPI 3 document. You can:

  • Download it: openapi.yaml — import it into Apidog, Postman, Insomnia, or use it to generate a client.
  • Try it live: every endpoint page includes a request builder that calls the Demo server (https://paypercloudv32.demo.paypuce.com) directly, so you can test without writing any code.

Json response format​

Success​

All the responses have the same format:

{
  "status": "success",
  "data": {
    // generic remote-action metadata...
    "details" : {
        /* custom data depending on remoteActionTypeId*/
    }
  }
}

These fields related to remote-action information are always present with remote-action related calls (e.g., create remote-action, get remote-action, list remote-actions ...) They identify the remote-action and its current status, type, and metadata (source, target, group, timestamps ...)

{
  "success": true,
  "data": {
    "id": 291,
    "uuid": "aa428ca3-811c-452f-a6a6-bf6d384b58a6",
    "sourcePid": "210200010004",
    "targetPid": "200200010004",
    "groupId": 835,
    "groupName": "PG2",
    "remoteActionStatusId": 100,
    "remoteActionStatus": "Pending",
    "remoteActionStatusAt": "2026-02-03T13:52:34.000000Z",
    "remoteActionTypeId": 10,
    "remoteActionType": "PURCHASE",
    "updatedAt": "2026-02-03T13:52:34.000000Z",
    "createdAt": "2026-02-03T13:52:34.000000Z",
    "webHook": "http://your.domain/testhook",
    "details" : {
        /* custom data depending on remoteActionTypeId*/
    }
  }
}

The specific remote-action data will be in the details sub-object. They are described in the related use case section (e.g., Purchase : amount, shouldPrintReceipt, allowedPaymentMethodIds ... ).

Error​

{
    "success": false,
    "error": {
        "message": "Some error message describing what went wrong",
        "code": 400
    },
    "data": [] //usually empty.
}
Response examples

On each page, pay attention to the right side of the page, you will find examples of request and response for each endpoint. The response example will show you the content of the data field. for different scenarios (1: success, 2:error, 3: wrong request...).

A screenshot of a computer Description automatically generated

Payment reference (purchaseUniqueId)​

Both Purchase and Refund accept an optional purchaseUniqueId (string, up to 30 characters). It is a payment reference forwarded to the payment terminal and attached to the card transaction, so it appears in your acquirer's transaction / settlement export.

Use it to carry your own reference (for example an invoice or order number such as 2026-FACT00450) all the way to the acquirer. This lets you reconcile payments in your ERP (e.g. Odoo): each settled transaction can be matched back to its source document.

  • If omitted, PayperCloud generates one and returns it in the response.
  • Max 30 characters: longer values are trimmed, shorter values are right-padded with spaces.

Webhooks​

webHook

✅ Webhooks are available in Production. Provide a webhook URL parameter in your requests to be notified of the final result — no polling required.

Webhooks are provided as parameter of each request and will be triggered when the remote-action is processed (successfully or not). They allow you to be notified of the result of the remote-action processing without having to poll our API. You can use them to update your system accordingly (e.g., mark a purchase as completed, print a receipt, etc ... ).
For webhook testing, you can use this: https://webhook.site .

Payload​

  • The payload is the same as in the Get Remote Action Status By Id endpoint.
  • Headers are following:
    • signature : 46ef52803a71d72096f148f120104afcb45c48c2219bda47230cedec8c36b148
    • x-remote-action-type : PURCHASE
    • x-remote-action-uuid : 009d78e1-81c7-4a24-8ea5-b519fbf9c1d6

Signature​

The webhook call will be signed using a secret defined in your Store configuration. This allows you to verify that the webhook calls are indeed coming from our system and not from a malicious actor. The signature is defined as following.

$payloadJson = json_encode($payload);
$signature = hash_hmac('sha256', $payloadJson, $secret);

Major Changes​

Version 3.2 of the API includes significant changes to improve security, clarity, and functionality. We also merged 2 paypuce applications to improve stability and maintanability. For more details, please refer to the Release Notes section.