# Get Started with Mastercard Gateway APIs
source: https://developer.mastercard.com/mastercard-gateway/documentation/tutorials-and-guides/get-started/index.md

## Overview {#overview}

The Mastercard Gateway provides a comprehensive API for merchants to accept online payments. This tutorial will guide you through the integration process from setup to going live.

### Prerequisites {#prerequisites}

Follow the Gateway Quick Start Guide to:

* Get started as a partner (Mastercard Gateway Merchant Manager users) with multiple API projects
* Get started as a merchant (Mastercard Gateway Merchant Administration users) with a single API project

### Good to know {#good-to-know}

Before starting your integration, you need to understand these concepts:

#### Payment Flow Basics {#payment-flow-basics}

* Orders: Container for payment transactions
* Transactions: Individual payment operations (PAY, AUTHORIZE, CAPTURE, REFUND, etc.)
* Cardholder-initiated payments: Payments where the customer is present
* Merchant-initiated payments: Automated payments (subscriptions, etc.)

#### Key Actors {#key-actors}

* Merchant: The business accepting payments
* Payer: The customer making the payment
* Gateway: Mastercard's payment processing system
* Acquirer: Bank that processes card transactions

## Step-by-Step Integration Guide {#step-by-step-integration-guide}

### Step 1: Define Your Requirements {#step-1-define-your-requirements}

#### Choose Payment Methods {#choose-payment-methods}

Determine which of the available payment methods you want to support:

* **Card Payments**: Domestic and International networks
* **Digital Wallets**: Apple Pay, Google Pay
* **Payment Plans**: Plan Amex, UniCredit
* **Account-to-Account** (A2A): ACH, Mono, payconiq
* **Buy Now, Pay Later**: Klarna, Mercado Pago
* **Vouchers**: OXXO
* **Bank Transfers**: SEPA, Open Banking
* **Verification**
* **Recurring Payments**

#### Plan Your Order Lifecycles {#plan-your-order-lifecycles}

Here are some of the elements of the order lifecycle with associated endpoints.

##### Create Order {#create-order}

* **Purpose**: Initialize a new order with amount, currency, and customer details.
* **Endpoint** : `POST /merchant/{merchantId}/order`

##### Authenticate (3D Secure) {#authenticate-3d-secure}

* **Purpose**: Perform payer authentication using 3DS.
* **Endpoint** : `POST /order/{orderId}/transaction/{transactionId}/authenticate`

##### Authorize Payment {#authorize-payment}

* **Purpose**: Request authorization from the issuer to reserve funds.
* **Endpoint** : `POST /order/{orderId}/transaction`

Payload includes `transaction.type = "AUTHORIZATION"`

##### Capture Payment {#capture-payment}

* **Purpose**: Capture previously authorized funds.
* **Endpoint** : `POST /order/{orderId}/transaction`

Payload includes `transaction.type = "CAPTURE"`

##### Refund {#refund}

* **Purpose**: Refund full or partial amount to the customer.
* **Endpoint** : `POST /order/{orderId}/transaction`

Payload includes `transaction.type = "REFUND"`

### Step 2: Select an Integration Method {#step-2-select-an-integration-method}

Choose based on your PCI compliance requirements and technical needs:

* **Hosted Checkout**: Create a checkout session where the Mastercard Gateway hosts a payment page UI that gathers payment information from the customer, so you need not handle sensitive data at all
* **Hosted Session**: Choose the layout and styling of your payment page, while reducing PCI compliance costs.
* **Direct Payment**: Control your transactions, manage your payment pages, and collect payment details
* **Hosted Batch**: Submit batch transactions securely and reliably for processing through the Mastercard Gateway
* **Mobile Integration**: Helps you develop a mobile app that accepts digital payments through the Mastercard Gateway
* **Shopping Cart Plugin**: Online store that allows customers to select, review, and purchase products.

### Step 3: Set Up API Authentication {#step-3-set-up-api-authentication}

Choose your client authentication method.

### Step 4: Basic API Integration {#step-4-basic-api-integration}

#### Base URL Structure {#base-url-structure}

`https://[region]-gateway.mastercard.com/api/rest/version/[version]/merchant/[merchantId]/`

#### Common Transaction Types {#common-transaction-types}

* PAY
* AUTHORIZE
* CAPTURE

```PAY
{
  "apiOperation": "PAY",
  "order": {
    "amount": "10.00",
    "currency": "USD",
    "id": "order-123"
  },
  "sourceOfFunds": {
    "type": "CARD",
    "provided": {
      "card": {
        "number": "5123456789012346",
        "expiry": {
          "month": "12",
          "year": "25"
        },
        "securityCode": "123"
      }
    }
  }
}
```

```AUTHORIZE
{
  "apiOperation": "AUTHORIZE",
  "order": {
    "amount": "10.00",
    "currency": "USD",
    "id": "order-123"
  },
  "sourceOfFunds": {
    "type": "CARD",
    "provided": {
      "card": {
        "number": "5123456789012346",
        "expiry": {
          "month": "12",
          "year": "25"
        },
        "securityCode": "123"
      }
    }
  }
}
```

```CAPTURE
{
  "apiOperation": "CAPTURE",
  "transaction": {
    "amount": "10.00",
    "currency": "USD"
  }
}
```

#### HTTP Request Format {#http-request-format}

```sh
curl -X PUT   https://[region]-gateway.mastercard.com/api/rest/version/[version]/merchant/[merchantId]/order/[orderId]/transaction/[transactionId]
    -H 'Content-Type: application/json'
    -u 'merchant.[merchantId]:[password]'
    -d '[transaction_data]'
```

### Step 5: Configure Your Test Account {#step-5-configure-your-test-account}

Access the Merchant Administration portal to:

1. Configure payment methods and supported card types
2. Set up webhook notifications for transaction updates
3. Configure EMV 3D-Secure settings if required
4. Set up fraud filters and risk management rules
5. Create additional operators with appropriate access levels

### Step 6: Implement Security Features {#step-6-implement-security-features}

Add 3DS for enhanced security:

#### 3D Secure Authentication {#3d-secure-authentication}

```json
{
  "3DSecure": {
    "authenticationRedirect": {
      "responseUrl": "https://your-site.com/3ds-callback",
      "pageGenerationMode": "SIMPLE"
    }
  }
}
```

### Step 7: Testing {#step-7-testing}

[Here is the information](https://developer.mastercard.com/mastercard-gateway/documentation/testing/index.md) you need to test Mastercard Gateway APIs.

### Step 8: Go Live {#step-8-go-live}

When testing is complete:

1. Request live credentials from your payment service provider
2. Update endpoint URLs to production
3. Implement monitoring and logging
4. Set up alerting for failed transactions
5. Configure backup procedures

Remember to thoroughly test your integration before going live and maintain security best practices throughout the process.