Getting Started Guides

Get Started: Working With Push-to-Card Transactions

Use a Push-to-Card transaction to move money from a RocketKOR Financial Account to a debit card.

In this guide, we’ll send funds from a Business Financial Account to a Customer Financial Account:

The Business Financial Account is the debit account (provides the funds). This account can be an internal or integrated bank Financial Account. In our example, we’ll use an integrated bank Financial Account.

Note An external Financial Account owned by the Business Account could also be used as the debit account. However, the transaction would be processed as a multi-leg transaction (MLT).
The Customer Financial Account is the credit account (receives the funds). This must be an external card Financial Account linked to a debit card.

In this guide, you’ll learn how to:

Add a Financial Account for a Customer.
Create a Push-to-Card transaction.
View the transaction’s status history.
Retrieve the transaction.

Before You Start

Sandbox Account: Sign up for a RocketKOR sandbox account. When your sandbox account is created, one or more Service Accounts will be created for your Business Account. A Service Account is a non-human user of a Business Account that performs functions (such as creating transactions) via the RocketKOR APIs on behalf of the Business Account.

Authentication: Before you can call the APIs, you must authenticate a Service Account by exchanging the account’s API key and secret for an access token.

Customer Account: Ensure the Business Customer or Individual Customer has an active Customer Account.

Step 1: Add a Financial Account for the Customer

Make sure an external card Financial Account has been created for the Customer. This Financial Account must be linked to the Customer’s debit card.

Step 2: Create a Push-to-Card Transaction

Create a Push-to-Card transaction that will transfer funds to the Customer’s debit card.

In our example, we’ll transfer funds from the Business Account’s integrated bank Financial Account to the Customer’s external card Financial Account.

At a minimum, the request must include the following information. The request must also include an idempotency key that uniquely identifies the request. In the case of a network error, the idempotency key allows you to call the API multiple times without creating duplicate requests.

Parameter	Description
debitFinancialAccountId	ID of the Financial Account used as the debit account (source of funds) for the transaction. In our example, this is an integrated bank Financial Account owned by the Business Account.
creditFinancialAccountId	ID of the Financial Account used as the credit account (receiver of funds) for the transaction. In our example, this is an external card Financial Account owned by the Customer.
transactionType	Type of transaction. Push-to-Card transactions always use the SEND transaction type. This pushes funds from the debit account to the credit account.
solution	Name of the RocketKOR solution used for the transaction. In our example, we’ll use push-to-card.
paymentReasonId	ID representing the payment reason for the transaction. In our example, we’ll use payment-of-rebates.
amount	Amount to be transferred from the debit account to the credit account. The amount must conform to any transaction limits.
currency	Currency used for the transaction. Must be USD.

API Reference

Create an SLT

Endpoint

POST /v1/transactions

Request Example

				
					{
  "debitFinancialAccountId": "e990236c-d3d1-4843-ade9-363d2217cd40",
  "creditFinancialAccountId": "08e5c7d1-4a39-44a3-a5ad-2a306faa60d83",
  "transactionType": "SEND",
  "solution": "push-to-card",
  "paymentReasonId": "payment-of-rebates",
  "amount": "200.00",
  "currency": "USD"
}

Response Example

Returns the SLT object.

Make a note of the transaction id. You’ll need this ID in the next steps when you check the transaction status and retrieve the transaction.

				
					{
  "id": "57739abd-9310-4094-9b48-c2c8668aa5c3",
  "businessAccountId": "de30132c-e67a-4af7-89ec-f2109863b7f7",
  "debitFinancialAccountId": "e990236c-d3d1-4843-ade9-363d2217cd40",
  "creditFinancialAccountId": "08e5c7d1-4a39-44a3-a5ad-2a306faa60d83",
  "transactionType": "SEND",
  "solution": "push-to-card",
  "paymentReasonId": "payment-of-rebates",
  "paymentReason": "Payment of rebates",
  "amount": "200.00",
  "currency": "USD",
  ...
}

Step 3: Check the Transaction Status

View the transaction’s status history, including the current status.

API Reference

Retrieve an SLT’s Status History

Endpoint

GET /v1/transaction-histories In the request, pass the transaction id from step 2 to the transactionId query parameter.

Response Example

Returns an array of SLT Status objects. These objects represent the statuses that have been assigned to the transaction during the transaction processing lifecycle.

				
					{
  "totalElements": 2,
  "totalPages": 1,
  "number": 0,
  "numberOfElements": 2,
  "hasNext": false,
  "content": [
    {
      "createdBy": {
        "id": "f29200b9-4817-474a-a958-aa8b352f2e45",
        "type": "internal"
      },
      "createdAt": "2023-02-03T05:00:05.634158Z",
      "id": "aafcea88-2b6d-4151-b1ce-9e4deb9547af",
      "transactionId": "23733586-9135-42a5-8365-d0a2ec9eead0",
      "eventType": "STATUS_CHANGE",
      "description": "Transaction status changed to ‘PENDING’"
    },
    {
      "createdBy": {
        "id": "f29200b9-4817-474a-a958-aa8b352f2e45",
        "type": "internal"
      },
      "createdAt": "2023-02-03T04:00:05.634158Z",
      "id": "d7bed9a7-c55f-4b13-8d46-835f65d06939",
      "transactionId": "23733586-9135-42a5-8365-d0a2ec9eead0",
      "eventType": "CREATE",
      "description": "New transaction created"
    }
  ]
}

Step 4: Retrieve the Transaction

Retrieve the transaction details.

API Reference

Retrieve an SLT

Endpoint

GET /v1/transactions/{transactionId}

In the request:

Pass the transaction id from step 2 to the transactionId parameter.
Use the embed query parameter to embed subresources in the response, such as details for the debit and credit Financial Accounts.

Response Example

Returns the SLT object. The following example includes embedded subresources for the debit and credit Financial Accounts used in the transaction.

				
					{
  "id": "57739abd-9310-4094-9b48-c2c8668aa5c3",
  "businessAccountId": "de30132c-e67a-4af7-89ec-f2109863b7f7",
  "debitFinancialAccountId": "e990236c-d3d1-4843-ade9-363d2217cd40",
  "creditFinancialAccountId": "08e5c7d1-4a39-44a3-a5ad-2a306faa60d83",
  "transactionType": "SEND",
  "solution": "push-to-card",
  "paymentReasonId": "payment-of-rebates",
  "paymentReason": "Payment of rebates",
  "amount": "200.00",
  "currency": "USD",
  ...
  "_embedded": {
    "debitFinancialAccount": {
      "id": "e990236c-d3d1-4843-ade9-363d2217cd40",
      "businessAccountId": "de30132c-e67a-4af7-89ec-f2109863b7f7",
      "name": "Checking Account",
      "category": "INTEGRATED",
      "type": "BANK",
      "subtype": "CHECKING",
      ....
    },
    "creditFinancialAccount": {
      "id": "08e5c7d1-4a39-44a3-a5ad-2a306faa60d83",
      "businessAccountId": "de30132c-e67a-4af7-89ec-f2109863b7f7",
      "name": "Debit Card",
      "category": "EXTERNAL",
      "type": "CARD",
      "subtype": "DEBIT",
      ...
    }
  }
}

Next Steps

Create ACH transactions.
Create Wire transactions.

Get Started: Working With Push-to-Card Transactions

Before You Start

Step 1: Add a Financial Account for the Customer

Step 2: Create a Push-to-Card Transaction

API Reference

Endpoint

Request Example

Response Example

Step 3: Check the Transaction Status

API Reference

Endpoint

Response Example

Step 4: Retrieve the Transaction

API Reference

Endpoint

Response Example

Next Steps

ON THIS PAGE