README

Table of Contents

• Overview
  • Compatibility
  • References
  • Versioning and Deprecation Policy
• Usage
  • Prerequisites
  • Adding the Library to Your Project
  • Loading the Signing Key
  • Creating the OAuth Authorization Header
  • Signing HTTP Client Request Objects
  • Integrating with OpenAPI Generator API Client Libraries

Overview

Zero dependency library for generating a Mastercard API compliant OAuth signature.

Compatibility

PHP 5.6+

References

• OAuth 1.0a specification
• Body hash extension for non application/x-www-form-urlencoded payloads

Versioning and Deprecation Policy

• Mastercard Versioning and Deprecation Policy

Usage

Prerequisites

Before using this library, you will need to set up a project in the Mastercard Developers Portal.

As part of this set up, you'll receive credentials for your app:

• A consumer key (displayed on the Mastercard Developer Portal)
• A private request signing key (matching the public certificate displayed on the Mastercard Developer Portal)

Adding the Library to Your Project

composer require mastercard/oauth1-signer

Loading the Signing Key

A private key object can be created by calling the AuthenticationUtils::loadSigningKey function:

use Mastercard\Developer\OAuth\Utils\AuthenticationUtils;
// …
$signingKey = AuthenticationUtils::loadSigningKey(
                '<insert PKCS#12 key file path>',
                '<insert key alias>', 
                '<insert key password>');

Creating the OAuth Authorization Header

The method that does all the heavy lifting is OAuth::getAuthorizationHeader. You can call into it directly and as long as you provide the correct parameters, it will return a string that you can add into your request's Authorization header.

use Mastercard\Developer\OAuth\OAuth;
// …
$consumerKey = '<insert consumer key>';
$uri = 'https://sandbox.api.mastercard.com/service';
$method = 'POST';
$payload = 'Hello world!';
$authHeader = OAuth::getAuthorizationHeader($uri, $method, $payload, $consumerKey, $signingKey);

Signing HTTP Client Request Objects

Alternatively, you can use helper classes for some of the commonly used HTTP clients.

These classes, provided in the Mastercard\Developer\Signers\ namespace, will modify the provided request object in-place and will add the correct Authorization header. Once instantiated with a consumer key and private key, these objects can be reused.

Usage briefly described below, but you can also refer to the test namespace for examples.

• cURL
• GuzzleHttp

cURL

POST example

use Mastercard\Developer\Signers\CurlRequestSigner;
// …
$method = 'POST';
$uri = 'https://sandbox.api.mastercard.com/service';
$payload = json_encode(['foo' => 'bår']);
$headers = array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($payload)
);
$handle = curl_init($uri);
curl_setopt_array($handle, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_CUSTOMREQUEST => $method, CURLOPT_POSTFIELDS => $payload));
$signer = new CurlRequestSigner($consumerKey, $signingKey);
$signer->sign($handle, $method, $headers, $payload);
$result = curl_exec($handle);
curl_close($handle);

GET example

use Mastercard\Developer\Signers\CurlRequestSigner;
// …
$method = 'GET';
$baseUri = 'https://sandbox.api.mastercard.com/service';
$queryParams = array('param1' => 'with spaces', 'param2' => 'encoded#symbol');
$uri = $baseUri . '?' . http_build_query($queryParams);
$handle = curl_init($uri);
curl_setopt_array($handle, array(CURLOPT_RETURNTRANSFER => 1));
$signer = new CurlRequestSigner($consumerKey, $signingKey);
$signer->sign($handle, $method);
$result = curl_exec($handle);
curl_close($handle);

GuzzleHttp

use GuzzleHttp\Psr7\Request;
use Mastercard\Developer\Signers\PsrHttpMessageSigner;
// …
$payload = '{"foo":"bår"}';
$headers = ['Content-Type' => 'application/json'];
$request = new Request('POST', 'https://sandbox.api.mastercard.com/service', $headers, $payload);
$signer = new PsrHttpMessageSigner($consumerKey, $signingKey);
$signer.sign($request);

Integrating with OpenAPI Generator API Client Libraries

OpenAPI Generator generates API client libraries from OpenAPI Specs. It provides generators and library templates for supporting multiple languages and frameworks.

This project provides you with classes you can use when configuring your API client. These classes will take care of adding the correct Authorization header before sending the request.

Generators currently supported:

• php

php

OpenAPI Generator

Client libraries can be generated using the following command:

openapi-generator-cli generate -i openapi-spec.yaml -g php -o out

See also:

• OpenAPI Generator CLI Installation
• CONFIG OPTIONS for php

Usage of the PsrHttpMessageSigner

use GuzzleHttp;
use OpenAPI\Client\Api\ServiceApi;
use OpenAPI\Client\Configuration
use Mastercard\Developer\Signers\PsrHttpMessageSigner;
// …
$stack = new GuzzleHttp\HandlerStack();
$stack->setHandler(new GuzzleHttp\Handler\CurlHandler());
$stack->push(GuzzleHttp\Middleware::mapRequest([new PsrHttpMessageSigner($consumerKey, $signingKey), 'sign']));
$options = ['handler' => $stack];
$client = new GuzzleHttp\Client($options);
$config = new Configuration();
$config->setHost('https://sandbox.api.mastercard.com');
$serviceApi = new ServiceApi($client, $config);
// …