API interaction

API version

Currently, two API versions are supported.

Please use the correct names for each version!

API v1	API v2
payment_method	payout_details
payments	payout_list
acquiring_payments	payment_list

Endpoint

How to generate a request

<server address> + /api/v{API version number} + <required method>

Example:

API v1: https://proxy-demo.pikepayments.com/api/v1/session/init/payout
API v2: https://proxy-demo.pikepayments.com/api/v2/session/init/payout

Server address

• For testing: https://proxy-demo.pikepayments.com
• For live transactions: https://proxy.pikepayments.com

Request format

All the data in requests to Pike and notifications from Pike is transmitted using the HTTP POST method. Message parameters are packed into a JSON object.

Authentication

In the headers of your requests to Pike, always pass the following data for authentication: your project identifier and request signature.

Authentication

Name	Mandatory	Type	Description
X-PARTNER-PROJECT	+	string	Project identifier (from your Pike manager)
X-PARTNER-SIGN	+	string	Request signature
X-PARTNER-SUBMERCHANT	-	string	Payer's identifier (for legal entities)

Request example with authentication

curl -X POST \
  https://proxy-demo.pikepayments.com/api/v1/session/create \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    // request body
  }'

Request signature

The signature is needed to verify the authenticity and integrity of requests. Pike verifies that the requests received are in fact from you (and are complete); you verify Pike's notifications the same way.

To create and verify a signature, you will need a secret key and a public key. Using your public key Pike will verify signatures of your incoming payments.

Generating a key pair

You need to generate a pair of keys on your side using the RSA signature algorithm.

Creating request body signature

The signature must be transmitted together with the request to Pike. You need to sign the request body as a whole in the form in which it is sent to Pike's server (after serializing the request body into JSON to send it over HTTP).

Use your secret key for signing the request. Create a signature using the SHA-256 algorithm. The resulting signature must then be transmitted in the Base64 format.

Verifying incoming requests from Pike

All outgoing requests from Pike are signed using Pike's own secret key.

Using Pike's public key, you need to verify the signatures of the requests coming from Pike on your side. The algorithm used is SHA-256. The signature is transmitted in the Base64 format.

Pike's public keys

• for live transactions
• for testing

Signature generation and validation examples

OpenSSL

# Generating a private key
$ openssl genrsa -out private.pem 2048

# Generating a public key based on the private key
$ openssl rsa -in private.pem -pubout > public.pem

# Creating myfile.txt file contents
$ echo test > myfile.txt

# Generating a signature
$ openssl dgst -sha256 -sign private.pem -out sha256.sign myfile.txt

# Signature ready for transfer
$ base64 sha256.sign

# Checking the signature
$ openssl dgst -sha256 -verify public.pem -signature sha256.sign myfile.txt
Verified OK

PHP

$data = "test";

//Obtaining the pointer to the private and public keys
$privateKey = openssl_pkey_get_private("file://private.pem");
$publicKey  = openssl_pkey_get_public("file://public.pem");

//Generating a signature based on the data using the private key
openssl_sign($data, $signature, $privateKey, OPENSSL_ALGO_SHA256);
openssl_free_key($privateKey);

//Encoding the signature into Base64 to transmit it
$base64Signature = base64_encode($signature);

//On receiving the signature, decoding it from Base64
$decodedSignature = base64_decode($base64Signature);

//Validating the received signature using the public key (success = 1)
$isValid = openssl_verify($data, $decodedSignature, $publicKey, OPENSSL_ALGO_SHA256);

Idempotency key

An idempotency key is a unique request identifier. You can generate it and use it to ensure that no request with the same unique identifier is attempted more than once. For example, this way you can avoid duplicate payments and payouts.

The idempotency key lifetime is 24 hours.

Format

Specify the idempotency key in the request header.

Name	Mandatory	Type	Description
X-PARTNER-IDEMPOTENCY-KEY	-	string	Idempotency key (from 4 to 64 characters)

Example of a request with an idempotency key

curl -X POST \
  https://proxy-demo.pikepayments.com/api/v1/session/create \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -H 'X-PARTNER-IDEMPOTENCY-KEY: testkey' \
  -d '{
    // request body
  }'

Methods supporting the idempotency key feature

• session/create
• session/init/payout
• session/start/payout
• session/init/payment
• session/start/payment
• session/confirm
• session/capture
• session/cancel
• session/refund

Errors

• idempotency_key_params_mismatch — The key has already been used for another session
• idempotency_key_already_exists — The previous request with the same key is still in progress
• idempotency_key_not_supported — This method cannot be used with an idempotency key

Payment session

All operations in the API take place within a payment session. A single payment session can combine multiple operations, such as a payment and a refund.