Create an STP Transaction

Create an STP (straight-through processing) transaction to send money to a Recipient’s debit card, even if the Recipient has not yet been created in RocketKOR. As part of the STP process, RocketKOR will create a new Recipient Account and a new Financial Account for the Recipient’s debit card. This allows you to create a transaction and add the Recipient and their debit card to RocketKOR in a single step.

You can also create an STP transaction if the Recipient already exists in RocketKOR. In this case, RocketKOR will use the existing Recipient Account. If the Recipient already has a Financial Account linked to their debit card, RocketKOR will use the existing Financial Account.

The API will perform the following operations:

Create a Recipient Account (if one does not already exist).
Create an external card Financial Account for the Recipient’s debit card (if one does not already exist).
Create a SEND transaction request to send money to the Recipient’s debit card.

Endpoint

POST /v1/stp-transactions

Authorization Header

Authorization: Bearer <access_token>

Request Body

idempotencyKey REQUIRED

string

A unique string that identifies the request. Can be a v4 UUID or any other unique string with a minimum length of 6 characters and a maximum length of 255 characters.

If a network error occurs, you can safely retry the request using the same idempotency key and the request will only be executed once. This ensures that calling the API multiple times will not result in duplicate requests. For more information, see Idempotent Calls.

entity REQUIRED

object

Recipient information.

category REQUIRED

string enum, values: INDIVIDUAL, BUSINESS

Type of Recipient.

firstName REQUIRED

string, max length: 50

Recipient’s first name.

lastName REQUIRED

string, max length: 50

Recipient’s last name.

businessName CONDITIONAL

string, max length: 50

Business name. Required if recipientType is BUSINESS.

mobileNumber CONDITIONAL

string

Recipient’s phone number. Required if notify is set to true. The phone number can be entered in any of the following formats:

[+][country code][phone number including area code] (example: +14151234)
[country code][phone number including area code] (example: 14151234)
[phone number including area code] (example: 4151234)

string, max length: 100

Recipient’s email address.

financial REQUIRED

object

Recipient’s debit card information and billing address.

cardData REQUIRED

object

Recipient’s debit card.

expiry REQUIRED

string, format: YY-MM

Expiry date for the card.

cardNumber REQUIRED

string

Card number.

billingAddress

object

Billing address for the debit card.

addressLine1 REQUIRED

string, min length: 1, max length: 40

First line of the street address.

addressLine2

string, min length: 1, max length: 40

Second line of the street address.

adressLine3

string, min length: 1, max length: 40

Third line of the street address.

city REQUIRED

string, min length: 1, max length: 40

City.

state REQUIRED

string, min length: 2, max length: 3

State, province, or territory. Must be an ISO 3166-2 uppercase alpha 2-character or 3-character country subdivision code. For example, Missouri is MO.

country REQUIRED

string, min length: 3, max length: 3

Country code. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

postalCode REQUIRED

string, max length: 10

Zip code or postal code.

transaction REQUIRED

object

Transaction details.

financialAccountId REQUIRED

string (UUID)

ID of the Financial Account used as the debit account (source of the funds) for the transaction.

paymentReasonId REQUIRED

string, max length: 50

ID representing the payment reason for the transaction. Use the Payment Reasons API to retrieve a list of available payment reasons.

amount REQUIRED

string

Amount to send to the Recipient’s debit card.

notify

boolean

Whether to send a notification to the Recipient when the transaction is created. If set to true, mobileNumber is required.

Returns

Returns details for the Recipient Account, Financial Account, and transaction. The following fields are returned.

idempotencyKey

string

A unique string that identifies the request. Can be a v4 UUID or any other unique string with a minimum length of 6 characters and a maximum length of 255 characters.

recipientAccountId

string

ID of the Recipient Account.

financialAccountId

string

ID of the external card Financial Account linked to the Recipient’s debit card.

transactionId

string

ID of the transaction in the RocketKOR system.

transactionStatus

string enum, values: COMPLETED, ERROR

Transaction status. The following values are supported:

COMPLETED The transaction has been completed.
FAILED The transaction could not be processed due to one or more errors (for example, the network is unavailable after a number of retries).

SAMPLE REQUEST

				
					{
  "idempotencyKey": "1bd5257a-3e88-4e39-b708-310a83950fad",
  "entity": {
    "category": "INDIVIDUAL",
    "firstName": "Sam",
    "lastName": "Smith",
    "businessName": "",
    "mobileNumber": "+15551234567",
    "email": "sam.smith@abc.com"
  },
  "financial": {
    "cardData": {
      "expiry": "2025-04",
      "cardNumber": "49927398716"
    },
    "billingAddress": {
      "addressLine1": "50 King St",
      "addressLine2": "",
      "addressLine3": "",
      "city": "New York",
      "state": "NY",
      "country": "USA",
      "postalCode": "10001"
    }
  },
  "transaction": {
    "financialAccountId": "7e85e0d0-d273-4856-972a-95cd81031e5a",
    "paymentReasonId": "deposit",
    "amount": "50.00"
  },
  "notify": false
}

SAMPLE RESPONSE

				
					{
  "idempotencyKey": "1bd5257a-3e88-4e39-b708-310a83950fad",
  "recipientAccountId": "85081169-7fc7-40ba-9376-6bf9c84e0527",
  "financialAccountId": "a718618a-6e4e-4b9a-9345-3bfa82e77fa1",
  "transactionId": "3a4323c6-5ca6-4849-8b31-c76a829abf62",
  "transactionStatus": "COMPLETED"
}