Clover Payment API using OAuth and Card Tokenization
In this article, we will walk through the process of integrating the Clover Payment API using OAuth for authentication and card tokenization for secure payments. We will cover the necessary steps, including obtaining OAuth tokens, API access keys, and handling payments.
Prerequisites
- Clover Sandbox Account: Create a sandbox account on Clover.
- OAuth Credentials: Register an application on Clover's developer portal to get the
APP_ID
andAPP_SECRET
. - Laravel Framework: Ensure you have a Laravel project set up.
Step-by-Step Guide
Step 1: Retrieve OAuth Token
Necessary Inputs
- Client ID: The application ID, retrieved from environment variables.
- Client Secret: The application secret, retrieved from environment variables.
- Authorization Code: The authorization code obtained from the OAuth callback URL.
Request OAuth Token
Make a POST request to the OAuth token endpoint:
Endpoint: https://sandbox.dev.clover.com/oauth/token
Parameters:
client_id
: Application ID.client_secret
: Application secret.code
: Authorization code.grant_type
:authorization_code
.
Response Handling:
- On success, log and store the access token.
- On failure, log the error and return a JSON response with an error message.
$tokenResponse = $this->makeCURLRequest('https://sandbox.dev.clover.com/oauth/token', [
'client_id' => $clientId,
'client_secret' => $clientSecret,
'code' => $authorizationCode,
'grant_type' => 'authorization_code'
]);
if (!$tokenResponse || !isset($tokenResponse['access_token'])) {
Log::error('Failed to obtain OAuth token', ['response' => $tokenResponse]);
return response()->json(['error' => 'Failed to obtain OAuth token'], 400);
}
$token = $tokenResponse['access_token'];
Log::info('OAuth token obtained', ['token' => $token]);
Step 2: Retrieve API Access Key
Request API Access Key
Make a GET request to the API access key endpoint:
Endpoint: https://scl-sandbox.dev.clover.com/pakms/apikey
Headers:
Authorization
: Bearer {token}Content-Type
: application/json
Response Handling:
- On success, log and store the API access key.
- On failure, log the error and return a JSON response with an error message.
$pakmsResponse = $this->makeCURLRequest('https://sandbox.dev.clover.com/pakms/apikey', [], [
'Authorization: Bearer ' . $token,
'Content-Type: application/json'
], 'GET');
if (!$pakmsResponse || !isset($pakmsResponse['apiAccessKey'])) {
Log::error('Failed to obtain API access key', ['response' => $pakmsResponse]);
return response()->json(['error' => 'Failed to obtain API access key'], 400);
}
$apiAccessKey = $pakmsResponse['apiAccessKey'];
Log::info('API access key obtained', ['apiAccessKey' => $pakmsResponse]);
Step 3: Tokenize Credit Card
Encrypt Card Number
Encrypt the card number using the encryptPan
method.
Prepare Card Data
Include encrypted card data, expiration month and year, CVV, and card brand.
Request Card Token
Make a POST request to the card token endpoint:
Endpoint: https://token-sandbox.dev.clover.com/v1/tokens
Parameters:
- Card data.
Headers:
accept
: application/jsonapikey
: {apiAccessKey}
Response Handling:
- On success, log and store the card token.
- On failure, log the error and return a JSON response with an error message.
$encryptedPan = $this->encryptPan('00000000' . $cardNumber);
$cardData = [
'card' => [
'encrypted_pan' => $encryptedPan,
'transarmor_key_id' => '00000000',
'first6' => substr($cardNumber, 0, 6),
'last4' => substr($cardNumber, -4),
'exp_month' => $exp_month,
'exp_year' => $exp_year,
'cvv' => $cvv,
'brand' => 'DISCOVER'
]
];
$cardTokenResponse = $this->makeCURLRequest('https://token-sandbox.dev.clover.com/v1/tokens', $cardData, [
'accept: application/json',
'apikey: ' . $apiAccessKey
]);
if (!$cardTokenResponse || !isset($cardTokenResponse['id'])) {
Log::error('Failed to tokenize card', ['response' => $cardTokenResponse]);
return response()->json(['error' => 'Failed to tokenize card'], 400);
}
$cardToken = $cardTokenResponse['id'];
Log::info('Card tokenized successfully', ['cardToken' => $cardToken]);
Step 4: Make Payment
Prepare Payment Data
Include amount, currency, card token, description, and receipt email.
Request Payment
Make a POST request to the payment endpoint:
Endpoint: https://sandbox.dev.clover.com/v1/payments
Parameters:
- Payment data.
Headers:
Authorization
: Bearer {token}Content-Type
: application/json
Response Handling:
- On success, log the successful payment response and return a JSON response with a success message.
- On failure, log the error and return a JSON response with an error message.
$paymentData = [
'amount' => $totalAmount,
'currency' => 'USD',
'source' => $cardToken,
'description' => 'Charge from ' . $clientId,
'receipt_email' => $email
];
$paymentResponse = $this->makeCURLRequest('https://sandbox.dev.clover.com/v1/payments', $paymentData, [
'Authorization: Bearer ' . $token,
'Content-Type: application/json'
]);
if (!$paymentResponse || !isset($paymentResponse['id'])) {
Log::error('Failed to make payment', ['response' => $paymentResponse]);
return response()->json(['error' => 'Failed to make payment'], 400);
}
Log::info('Payment made successfully', ['response' => $paymentResponse]);
return response()->json(['success' => 'Payment made successfully', 'response' => $paymentResponse]);
Conclusion
Integrating the Clover Payment API involves several steps, including obtaining OAuth tokens, API access keys, and handling card tokenization and payments. By following the detailed steps outlined in this guide, you can securely process payments using Clover's API.