> ## Documentation Index
> Fetch the complete documentation index at: https://developers.orchestrasolutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first API call to Orchestra in under 5 minutes.

This guide walks you through creating a sandbox account, setting up mock payment gateways, and making your first test charge. No external payment provider accounts required.

<Note>
  This quickstart uses Orchestra's built-in mock payment gateways for immediate testing. When you're ready for production, see [Add a Payment Provider](/getting-started/add-payment-provider).
</Note>

## Setup

<Steps>
  <Step title="Create Orchestra Account">
    Sign up at [portal.orchestrasolutions.com](https://portal.orchestrasolutions.com).
  </Step>

  <Step title="Generate API Key">
    Create an API key to authenticate your requests:

    1. Go to **[API Keys > Create](https://portal.orchestrasolutions.com/#/apikey/create)**
    2. Enter a **Name** for the key (e.g., "Development")
    3. Ignore the **User** setting for now - when you're ready, see [Managing Users and Permissions](/getting-started/create-account#managing-users)
    4. Click **Save**
    5. **Copy the key immediately** - you won't see it again

    <Note>
      Copy the key now - you won't be able to view it again.
    </Note>
  </Step>

  <Step title="Create Mock Payment Gateway Accounts">
    <Info>
      Mock PSPs are test gateways that return predictable success or failure responses regardless of input. They let you test both code paths without external payment provider accounts. See the Mock Payment Gateways guide for details on limitations and capabilities.
    </Info>

    Set up test gateways in the Portal:

    **Success Gateway:**

    1. Go to **Resources** > **Payment Gateway Account** > **Create**
    2. **Name**: `testSuccess`
    3. **Gateway**: `NULLSuccess`
    4. Click **Save**

    **Failure Gateway (for testing):**

    * **Name**: `testFailure`
    * **Gateway**: `NULLFailure`
  </Step>
</Steps>

## Choose Your Approach: Payments Library or REST API

<CardGroup cols={2}>
  <Card title="Payments Library" icon="browser">
    **Use when:** Customers enter cards in your frontend. Pre-built UI, reduced PCI scope, supports digital wallets (Apple Pay, Google Pay).

    **Demonstrates:**

    * Session creation
    * Frontend integration with payment buttons
    * Result validation
  </Card>

  <Card title="REST API" icon="code">
    **Use when:** You collect card details on your backend. Full control, mobile apps, recurring payments, custom flows.

    **Demonstrates:**

    * Basic charges
    * Tokenization for PCI scope reduction
  </Card>
</CardGroup>

<Tabs>
  <Tab title="Payments Library" icon="browser">
    ### 1. Create eWallet Account

    Create an eWallet Account in the Portal:

    1. Go to **Resources** > **eWallet Accounts** > **Add Account**
    2. Name it `testWallet`
    3. Select the eWallet Type to be "CardPay"
    4. Set Merchant Identifier to be \[your\_company\_name].com.orchestrasolutions
    5. Set Merchant Display Name to be your company name
    6. Disregard for now all other fields - when you're ready to set up real use case processes, see [Creating eWallet Accounts](/getting-started/create-ewallet-account)
    7. Click **Save**

    ### 2. Install Library

    ```bash theme={null}
    npm install @orchestrasolutions/ewallet
    ```

    ### 3. Create Session (Backend)

    ```bash theme={null}
    curl --location 'https://api.orchestrasolutions.com/EWalletOperations' \
    --header 'X-Api-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "operation": "CHARGE",
      "paymentGatewayAccountId": "testSuccess",
      "allowedeWalletAccountIds": ["testWallet"],
      "mode": "TEST",
      "currencyCode": "USD",
      "countryCode": "US",
      "amount": 2.56,
      "allowedBrands": ["Visa", "MasterCard"]
    }'
    ```

    ### 4. Display Payment Button (Frontend)

    ```html theme={null}
    <div id="card-button"></div>
    ```

    ```javascript theme={null}
    import * as eWallet from '@orchestrasolutions/ewallet';

    // Initialize with JWT from backend
    const engine = new eWallet.Engine(jwt);

    // Check available payment methods
    const available = await engine.checkAvailability();

    // Display card payment button
    engine.payBy(
      [{ name: 'CardPay', domEntitySelector: '#card-button' }],
      handleResult,
      undefined
    );

    function handleResult(result) {
      // User cancelled
      if (!result) {
        console.log('Payment cancelled');
        return;
      }

      const [data] = engine.parseResultToken(result.token);
      console.log('Payment successful:', data);
      // Send result.token to backend for validation
    }
    ```

    <Info>
      This is where credit card details are submitted on the frontend. The Payments Library handles card collection and tokenization, keeping sensitive data out of your backend code.
    </Info>

    ### 5. Validate Result (Backend) - Optional

    <Info>
      Validate the result token received from Orchestra on the client side and passed to your server. This ensures the token wasn't altered between the client and server.
    </Info>

    ```bash theme={null}
    curl --location 'https://api.orchestrasolutions.com/EWalletOperations/validateResults' \
    --header 'X-Api-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '"RESULT_TOKEN_FROM_FRONTEND"'
    ```

    ***

    ## You're in

    You just completed an Orchestra integration using the Payments Library with mock PSPs. These examples demonstrate Orchestra's key capabilities without requiring external payment provider accounts.

    **Ready for production?** See [Add a Payment Provider](/getting-started/add-payment-provider) to configure real gateways. Your code stays the same - just swap the gateway account names.

    ### What's Next

    <CardGroup cols={2}>
      <Card title="Complete Example" icon="code" href="/guides/library/complete-example">
        Full server + client code you can clone and run
      </Card>

      <Card title="Library Setup" icon="gear" href="/guides/library/setup">
        Full configuration and customization
      </Card>

      <Card title="Payment Methods" icon="credit-card" href="/guides/library/supported-payment-methods">
        CardPay, ApplePay, GooglePay, PayPal, and more
      </Card>

      <Card title="Add Real Providers" icon="building-columns" href="/getting-started/add-payment-provider">
        Configure Stripe, Adyen, and more
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="REST API" icon="code">
    <Info>
      This example assumes you have access to the cards you will be charging. We're using a credit card test number below.
    </Info>

    ### 1. Basic Charge

    <CodeGroup>
      ```bash cURL theme={null}
      curl --location 'https://api.orchestrasolutions.com/PaymentGateway/charge' \
      --header 'X-Api-Key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "paymentGatewayAccountName": "testSuccess",
        "amount": 2.56,
        "currency": "USD",
        "myRef": "PaymentX11235",
        "card": {
          "cardType": "Visa",
          "cardHolderName": "Testing Tester",
          "cardNumber": "4242424242424242",
          "expirationYear": 2027,
          "expirationMonth": 12,
          "cvv": "123"
        }
      }'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch(
        'https://api.orchestrasolutions.com/PaymentGateway/charge',
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'X-Api-Key': 'YOUR_API_KEY'
          },
          body: JSON.stringify({
            paymentGatewayAccountName: 'testSuccess',
            amount: 2.56,
            currency: 'USD',
            myRef: 'PaymentX11235',
            card: {
              cardType: 'Visa',
              cardHolderName: 'Testing Tester',
              cardNumber: '4242424242424242',
              expirationYear: 2027,
              expirationMonth: 12,
              cvv: '123'
            }
          })
        }
      );

      const result = await response.json();
      console.log(result);
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
          'https://api.orchestrasolutions.com/PaymentGateway/charge',
          headers={
              'Content-Type': 'application/json',
              'X-Api-Key': 'YOUR_API_KEY'
          },
          json={
              'paymentGatewayAccountName': 'testSuccess',
              'amount': 2.56,
              'currency': 'USD',
              'myRef': 'PaymentX11235',
              'card': {
                  'cardType': 'Visa',
                  'cardHolderName': 'Testing Tester',
                  'cardNumber': '4242424242424242',
                  'expirationYear': 2027,
                  'expirationMonth': 12,
                  'cvv': '123'
              }
          }
      )

      print(response.json())
      ```
    </CodeGroup>

    ### 2. Expected Response

    ```json theme={null}
    {
      "authorizationCode": "fbbb8b",
      "currency": "USD",
      "amount": 2.56,
      "operationType": "Charge",
      "operationResultCode": "Success",
      "operationResultDescription": "Successful operation",
      "gatewayName": "NULLSuccess",
      "gatewayReference": "b362db",
      "gatewayResultCode": "OK",
      "gatewayResultDescription": "Gateway says: Successful operation",
      "gatewayResultSubCode": null,
      "gatewayResultSubDescription": null
    }
    ```

    ***

    ## You're in

    You just completed an Orchestra REST API integration using mock PSPs. These examples demonstrate Orchestra's key capabilities without requiring external payment provider accounts.

    **Ready for production?** See [Add a Payment Provider](/getting-started/add-payment-provider) to configure real gateways. Your code stays the same - just swap the gateway account names.

    ### What's Next

    <CardGroup cols={2}>
      <Card title="Multi-Gateway Failover" icon="layer-group" href="/guides/rest-api/multi-gateway-failover">
        Automatic failover across providers
      </Card>

      <Card title="Authorize & Capture" icon="hand-holding-dollar" href="/guides/rest-api/authorize-capture">
        Hold funds and capture later
      </Card>

      <Card title="Refunds & Voids" icon="rotate-left" href="/guides/rest-api/refunds-voids">
        Reverse transactions
      </Card>

      <Card title="Add Real Providers" icon="building-columns" href="/getting-started/add-payment-provider">
        Configure Stripe, Adyen, and more
      </Card>
    </CardGroup>
  </Tab>
</Tabs>