Developer docs
/
Direct transaction API integration
Last updated
These docs are intended for a developer audience.Dismiss

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 to tokenize payment data or use 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.

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.

  1. Log in or sign up to Rebilly.
  2. Obtain your organization ID and website ID:
    1. In the left navigation bar, press Settings .
    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.
  3. Obtain your secret API key:
    1. In the left navigation bar, press Automations .
    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.
Configure a payment gateway

To set up or configure a payment gateway, see Set up a payment 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.

Interactive example
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.
Loading...

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.

For detailed information about this API operation, see Create a payment instrument.

Interactive example
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.
Loading...

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.

Interactive example
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.
    4. In the paymentInstrumentId field, enter a payment instrument ID.
      Use the payment instrument ID you created in Step 2.
  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.
Loading...

Troubleshooting

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.

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.

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.

To view the transaction in the Rebilly UI, see View the transaction details.

Interactive example
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.
  5. Press Send.
Loading...
Previous page
Next page