# Mastercard Developer Account Setup Guide

## Overview

This guide walks you through setting up a Mastercard Developer account and configuring the necessary credentials for MPGS (Mastercard Payment Gateway Services) integration.

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Account Registration](#account-registration)
3. [Project Creation](#project-creation)
4. [API Credentials Setup](#api-credentials-setup)
5. [Sandbox Environment](#sandbox-environment)
6. [Production Environment](#production-environment)
7. [Verification and Testing](#verification-and-testing)
8. [Security Best Practices](#security-best-practices)

## Prerequisites

Before starting, ensure you have:

- A valid business email address
- Business registration details
- Payment processing license (for production)
- Basic understanding of OAuth 1.0a authentication
- Access to secure credential storage

## Account Registration

### Step 1: Create Developer Account

1. Visit [Mastercard Developer Portal](https://developer.mastercard.com)
2. Click "Create Account" or "Sign Up"
3. Fill in the registration form:
   - **Email**: Use your business email address
   - **First Name**: Your first name
   - **Last Name**: Your last name
   - **Company**: Your company name
   - **Country**: Your business location
   - **Phone**: Business phone number

4. Verify your email address
5. Complete the account verification process

### Step 2: Account Verification

1. Check your email for verification link
2. Click the verification link
3. Log in to the developer portal
4. Complete your profile information:
   - Business details
   - Developer experience
   - Integration requirements

## Project Creation

### Step 1: Create New Project

1. Log in to Mastercard Developer Portal
2. Navigate to "My Projects"
3. Click "Create New Project"
4. Fill in project details:
   - **Project Name**: "Mercury Device Middlelayer MPGS Integration"
   - **Description**: "Payment gateway integration for card transaction processing"
   - **Category**: "Payment Processing"
   - **Use Case**: "Payment Gateway Services"

### Step 2: Add MPGS API

1. In your project dashboard, click "Add API"
2. Search for "Payment Gateway Services" or "MPGS"
3. Select "Mastercard Payment Gateway Services"
4. Click "Add to Project"
5. Review and accept the terms of service

## API Credentials Setup

### Step 1: Generate OAuth 1.0a Credentials

1. In your project, navigate to "Credentials" or "Keys"
2. Click "Generate OAuth 1.0a Credentials"
3. **Consumer Key**: 
   - A 97-character string will be generated
   - Copy and store securely
   - Example format: `abc123def456ghi789jkl012mno345pqr678stu901vwx234yzb567cde890fgh123ijk456lmn789opq012rst345`

### Step 2: Generate Signing Certificate

1. Click "Generate Signing Certificate"
2. Choose certificate format: **PKCS#12 (.p12)**
3. Set a strong password for the certificate
4. Download the `.p12` file
5. Store the file and password securely

**Certificate Details:**
- **File Format**: PKCS#12 (.p12)
- **Key Length**: 2048-bit RSA
- **Signature Algorithm**: RSA-SHA256
- **Validity**: 2 years (renewable)

### Step 3: Download and Verify

1. Download the signing certificate (.p12 file)
2. Verify the certificate:
   ```bash
   openssl pkcs12 -info -in mastercard-signing-key.p12
   ```
3. Test certificate accessibility:
   ```bash
   openssl pkcs12 -in mastercard-signing-key.p12 -noout -info
   ```

## Sandbox Environment

### Step 1: Sandbox Configuration

1. In your project dashboard, locate "Sandbox Environment"
2. Note the sandbox endpoints:
   - **Base URL**: `https://test-gateway.mastercard.com`
   - **API Version**: `version/60` (or latest available)

### Step 2: Merchant Configuration

1. Navigate to "Sandbox Settings"
2. Configure test merchant:
   - **Merchant ID**: Will be provided (e.g., `TEST_MERCHANT_12345`)
   - **Currency**: USD (or your preferred currency)
   - **Processing Options**: Enable all transaction types

### Step 3: Test Data

Mastercard provides test card numbers for sandbox testing:

**Visa Test Cards:**
- `4111111111111111` (Approved)
- `4000000000000002` (Declined)

**Mastercard Test Cards:**
- `5555555555554444` (Approved)
- `5000000000000009` (Declined)

**American Express Test Cards:**
- `378282246310005` (Approved)
- `371449635398431` (Declined)

## Production Environment

### Step 1: Production Approval

1. Complete sandbox testing and integration
2. Submit production access request:
   - Integration test results
   - Security compliance documentation
   - Business verification documents

### Step 2: Production Credentials

Once approved:
1. Generate production OAuth credentials
2. Download production signing certificate
3. Configure production merchant account
4. Update application configuration

### Step 3: Production Endpoints

- **Base URL**: `https://gateway.mastercard.com`
- **API Version**: `version/60` (or latest)
- **Merchant ID**: Production merchant ID (provided by Mastercard)

## Verification and Testing

### Step 1: Credential Verification

Create a test script to verify OAuth signing:

```bash
# Test OAuth signature generation
curl -X POST \
  https://test-gateway.mastercard.com/api/rest/version/60/merchant/TEST_MERCHANT/session \
  -H "Authorization: OAuth oauth_consumer_key=\"YOUR_CONSUMER_KEY\", oauth_nonce=\"RANDOM_NONCE\", oauth_signature_method=\"RSA-SHA256\", oauth_timestamp=\"CURRENT_TIMESTAMP\", oauth_version=\"1.0\", oauth_signature=\"GENERATED_SIGNATURE\"" \
  -H "Content-Type: application/json" \
  -d '{"session":{"id":"SESSION_TEST"}}'
```

### Step 2: API Connectivity Test

1. Use the OAuth client to make a test API call
2. Create a test session
3. Verify response format and content
4. Check error handling

### Step 3: Integration Testing

1. Test complete transaction flow:
   - Session creation
   - Payment processing
   - Transaction status inquiry
2. Test error scenarios:
   - Invalid credentials
   - Network timeouts
   - API errors

## Security Best Practices

### Credential Storage

1. **Never commit credentials to version control**
2. **Use environment variables in production**
3. **Encrypt credentials at rest**
4. **Implement proper access controls**

### Certificate Management

1. **Store .p12 files securely**
2. **Use strong passwords**
3. **Rotate certificates before expiry**
4. **Monitor certificate validity**

### API Security

1. **Always use HTTPS**
2. **Validate SSL certificates**
3. **Implement request timeouts**
4. **Log security events**

### Monitoring

1. **Monitor API usage**
2. **Track failed authentication attempts**
3. **Alert on unusual activity**
4. **Regular security audits**

## Configuration Example

After completing the setup, your configuration should look like:

```elixir
# config/upstream_networks.exs
mastercard_mpgs_sandbox: %{
  network_type: :gateway,
  priority: 3,
  base_url: "https://test-gateway.mastercard.com",
  api_version: "version/60",
  mpgs_config: %{
    merchant_id: "TEST_MERCHANT_12345",
    endpoints: %{
      session: "/api/rest/{version}/merchant/{merchantId}/session",
      payment: "/api/rest/{version}/merchant/{merchantId}/order/{orderId}/transaction/{transactionId}",
      payment_inquiry: "/api/rest/{version}/merchant/{merchantId}/order/{orderId}"
    }
  },
  auth_config: %{
    consumer_key: "your_97_character_consumer_key_here",
    signing_key_file: "/secure/path/to/mastercard-signing-key.p12",
    signing_key_password: "your_secure_password"
  }
}
```

## Troubleshooting

### Common Issues

1. **Account Registration Issues**:
   - Check email verification
   - Verify business information
   - Contact Mastercard support

2. **Credential Generation Issues**:
   - Ensure project has MPGS API added
   - Check account verification status
   - Try different browser/clear cache

3. **Certificate Issues**:
   - Verify password complexity requirements
   - Check file download completion
   - Test certificate accessibility

### Support Contacts

- **Technical Support**: [Mastercard Developer Support](https://developer.mastercard.com/support)
- **Integration Support**: Available through developer portal
- **Business Support**: Contact your Mastercard account manager

## Next Steps

After completing the account setup:

1. ✅ **Configure Application**: Update `config/upstream_networks.exs`
2. ✅ **Set Environment Variables**: Configure `.env` file
3. ✅ **Test OAuth Integration**: Run OAuth client tests
4. ✅ **Verify API Connectivity**: Test basic API calls
5. 🔄 **Begin Phase 2**: Start API client development

## Documentation References

- [Mastercard Developer Portal](https://developer.mastercard.com)
- [MPGS API Documentation](https://developer.mastercard.com/product/payment-gateway-services)
- [OAuth 1.0a Specification](https://oauth.net/1/)
- [RSA-SHA256 Signature Method](https://tools.ietf.org/html/rfc3447)

---

**Last Updated**: October 7, 2025  
**Version**: 1.0  
**Status**: Complete