# Direct transaction API integration

This guide describes how to create a transaction by directly communicating with the Rebilly API.

If you are not PCI-DSS compliant, use the [FramePay JavaScript library](/docs/dev-docs/framepay) to tokenize payment data or use a [Hosted payment form](/docs/dev-docs/create-a-hosted-payment-form) to process payments.

## Prerequisites

To complete this guide, you need a Rebilly account, a website ID, an organization ID, and a secret API key. You must also have at least one payment gateway configured in your Rebilly account. If you are testing in the sandbox environment, a test payment gateway called `TestProcessor` is already configured.

details
summary
Obtain your organization ID, website ID, and secret API key
When you first log in to Rebilly, you create an organization as part of the setup process. A default website is created when a new organization is created. For more information, see [Organizations and websites](/docs/settings/organizations-and-websites).

1. [Log in or sign up to Rebilly](https://app-sandbox.rebilly.com/).
2. Obtain your organization ID and website ID:
  1. In the left navigation bar, press .
  2. In the **Management** section, press **My organization & websites**.
  3. In the **Organization details** section, note the **ID** value.
  4. In the **Website** section, note the **ID** value. For more information, see [Organizations and websites](/docs/settings/organizations-and-websites).
3. Obtain your secret API key:
  1. In the left navigation bar, press .
  2. In the **Development** section, press **API keys**.
  3. Optionally, if you have not created a secret key:
    1. In top right of the screen, press **Create API key**.
    2. In the **API key type** section, select **Secret**.
    3. Optionally, in the **Organizations** dropdown, select the organizations that can use the API key.
    4. Optionally, in the **Allowed IPs** field, enter the IP addresses that are permitted to use the API key.
    5. Press **Save API key**.
    6. Go to the API keys page.
  4. Select a secret key and copy the **Key** value.


details
summary
Configure a payment gateway
To set up or configure a payment gateway, see [Set up a payment gateway](/docs/settings/set-up-a-gateway).

## Step 1: Upsert a customer

This step creates or updates (upserts) a customer with a specified ID.

This operation prevents duplicate customers. If the customer already has an identifier within your system, that customer is updated. If the customer does not have an identifier, a new customer is created.

For detailed information about this API operation, see [Upsert a customer](/catalog/all/customers/putcustomer).

details
summary
Interactive example
details
summary
How to use the interactive example
1. Select the sandbox server environment:
  1. In the top right of the interactive example, press the **Environment** dropdown.
  2. Select **Sandbox server**.
2. Enter your organization ID:
  1. Locate `server /customers/{id}`, press `server`, then press .
  2. In the **Server variables** section, press **Edit**.
  3. In the **Value** field, enter your organization ID and press **Save**.
3. Enter your secret API key:
  1. Press **Security**.
  2. In the **API key** field, press `{{SecretApiKey}}`, then press **Set value**.
  3. In the **Value** field, enter your secret Rebilly sandbox API key and press **Save**.
4. Enter a customer ID:
  1. In the URL field, press `{{id}}`.
  2. Press **Edit in path**.
  3. In the **Value** field, enter a customer ID. 
Example: `cus_01HDP7FFX2PGDVH1995EA4QY95`.
5. Enter your website ID:
  1. Press **Body**.
  2. In the `websiteId` field, enter your website ID.
  3. Optionally, change the customer details.
6. Press **Send**. 
In the response, note the `id` value. This is the customer ID.


## Step 2: Create a payment instrument

This step creates a payment instrument for the customer you created in the previous step. The payment instrument can be a credit card, bank account, or other payment method supported by Rebilly. This example uses a payment card payment instrument and contains test payment card details. For more test payment card details, including payment cards to test failed transactions, see [Test payment cards, IBANs, and ACH details](/docs/tutorials/test-transactions#test-payment-cards-ibans-and-ach-details).

For detailed information about this API operation, see [Create a payment instrument](/catalog/all/payment-instruments/postpaymentinstrument/).

details
summary
Interactive example
details
summary
How to use the interactive example
1. Select the sandbox server environment:
  1. In the top right of the interactive example, press the **Environment** dropdown.
  2. Select **Sandbox server**.
2. Enter your organization ID:
  1. Locate `server /payment-instruments`, press `server`, then press .
  2. In the **Server variables** section, press **Edit**.
  3. In the **Value** field, enter your organization ID and press **Save**.
3. Enter your secret API key:
  1. Press **Security**.
  2. In the **API key** field, press `{{SecretApiKey}}`, then press **Set value**.
  3. In the **Value** field, enter your secret Rebilly sandbox API key and press **Save**.
4. Enter a customer ID:
  1. Press **Body**.
  2. In the `customerId` field, enter a customer ID. 
Example: `cus_01HDP7FFX2PGDVH1995EA4QY95`.
5. Press **Send**. 
In the response, note the `id` value. This is the ID of the payment instrument.


## Step 3: Create a transaction

This step creates a transaction using the customer and payment instrument you created in the previous steps. The transaction can be a sale, authorization, or other type of transaction supported by Rebilly. This example creates a sale transaction with a specified amount and currency and uses the payment instrument created in the previous step.

For detailed information about this API operation, see [Create a transaction](/catalog/all/transactions/posttransaction/).

details
summary
Interactive example
details
summary
How to use the interactive example
1. Select the sandbox server environment:
  1. In the top right of the interactive example, press the **Environment** dropdown.
  2. Select **Sandbox server**.
2. Enter your organization ID:
  1. Locate `server /transactions`, press `server`, then press .
  2. In the **Server variables** section, press **Edit**.
  3. In the **Value** field, enter your organization ID and press **Save**.
3. Enter your secret API key:
  1. Press **Security**.
  2. In the **API key** field, press `{{SecretApiKey}}`, then press **Set value**.
  3. In the **Value** field, enter your secret Rebilly sandbox API key and press **Save**.
4. Enter website ID, customer ID, and payment instrument ID:
  1. Press **Body**.
  2. In the `websiteId` field, enter your website ID.
  3. In the `customerId` field, enter a customer ID. 
Use the customer ID you created in [Step 1](#step-1-upsert-a-customer).
  4. In the `paymentInstrumentId` field, enter a payment instrument ID. 
Use the payment instrument ID you created in [Step 2](#step-2-create-a-payment-instrument).
5. Press **Send**. 
In the response, note the `id` value. This is the ID of the transaction. 
The `result` and `status` fields specify the outcome of the transaction. For example, if the transaction was successful, the `result` field is `approved` and the `status` field is `completed`.


### Troubleshooting

details
summary
No gateway accounts available for this transaction
If you receive a `declined` result with the reason `No gateway account available to process this transaction`, check your gateway account settings in Rebilly. Ensure that a gateway account is configured for the currency, payment method, and website ID. For more information, see [Set up a payment gateway](/docs/settings/set-up-a-gateway).

details
summary
Result unknown and status waiting-approval
If you receive a response with a `result` value of `unknown` and a `status` value of `waiting-approval`, the transaction requires user approval or interaction. For more information, see [User approval/interaction required](/catalog/all/transactions/posttransaction#section/User-approvalinteraction-required).

## Step 4: View the transaction

This step retrieves the transaction you created in the previous step. You can view the transaction details, including the status, amount, and payment method used.

For detailed information about this API operation, see [Get a transaction](/docs/dev-docs/api/transactions/gettransaction).

To view the transaction in the Rebilly UI, see [View the transaction details](/docs/data-tables/manage-payments#view-transaction-details).

details
summary
Interactive example
details
summary
How to use the interactive example
1. Select the sandbox server environment:
  1. In the top right of the interactive example, press the **Environment** dropdown.
  2. Select **Sandbox server**.
2. Enter your organization ID:
  1. Locate `server /transactions/{id}`, press `server`, then press .
  2. In the **Server variables** section, press **Edit**.
  3. In the **Value** field, enter your organization ID and press **Save**.
3. Enter your secret API key:
  1. Press **Security**.
  2. In the **API key** field, press `{{SecretApiKey}}`, then press **Set value**.
  3. In the **Value** field, enter your secret Rebilly sandbox API key and press **Save**.
4. Enter a transaction ID:
  1. In the URL field, press `{{id}}`, then press **Set value**.
  2. In the **Value** field, enter a transaction ID. 
Enter the `id` value from the response in [Step 3](#step-3-create-a-transaction).
5. Press **Send**.