Transactions

Overview#

With Zūm Rails, there are 2 ways to create transactions: using the portal or via API. When creating a transaction via API, the transaction type (ZumRailsType) must be specified.

There are four transaction types (ZumRailsType):

  • FundZumWallet
  • WithdrawZumWallet
  • AccountsPayable
  • AccountsReceivable

Zūm Payment Methods

info

For accounts payable use-case, Zūm Rails recommends you fund the Zūm Wallet first, so that the money can be quickly moved.

info

For accounts receivable use-case, Zūm Rails recommends you move funds from the User to the Zūm Wallet, then set up an automatic daily withdrawal at the end of each day to your funding source.

Creating a new transaction#

Use this endpoint to create a new transaction.

Method: POST

Endpoint: {{env}}/api/transaction

  1. If you want to send money from your Funding Source to Zūm Wallet, use ZumRailsType FundZumWallet and provide:
    • FundingSourceId
    • WalletId
  2. If you want to withdraw money from Zūm Wallet to your Funding Source, use ZumRailsType WithdrawZumWallet and provide:
    • FundingSourceId
    • WalletId
  3. If you want to send money (accounts payable) from your Zūm Wallet to a User, use ZumRailsType AccountsPayable and provide:
    • UserId
    • PaymentInstrumentId
    • WalletId
  4. If you want to withdraw money (accounts receivable) from a User to your Zūm Wallet, use ZumRailsType AccountsReceivable and provide:
    • UserId
    • PaymentInstrumentId
    • WalletId
{
"ZumRailsType": "AccountsPayable",
"TransactionMethod": "Ach",
"Amount": 123.45,
"Memo": "Memo",
"Comment": "This transaction is just a test from a wallet to user",
"UserId": "1d431e8b-...85452adb4eee",
"WalletId": "8ebd932b-...b92633e14297",
"PaymentInstrumentId": "92142401-...389ba0d87e75"
}

Request parameters

ParameterTypeMandatoryDescription
ZumRailsTypestringyesTransaction type
TransactionMethodstringyesTransaction method.
AmountdecimalyesTransaction amount
MemostringyesMemo description.
CommentstringnoInternal comment you might want to add.
FundingSourceIdguidnoFunding Source Id
WalletIdguidnoWallet Id
UserIdguidnoUser Id
PaymentInstrumentIdstringyesPayment instrument id
UserUser inputnoIt's possible to create a transaction without adding a user first. Simply pass the user object (instead of the UserId) into the transaction body. For reference, check the payload example of the user object here and pass this when you create a transaction.
ScheduledStartDatedatenoThe date when the transaction will be sent to the financial institution. Must be greater than today
ClientTransactionIdstringnoThis field can be used to store the Transaction id created in your system when the Transaction is initiated

TransactionMethod

MethodDescription
AchACH transaction
DebitCardDebit card transaction
CreditCardCredit card transaction

ZumRailsType

TypeDescription
FundZumWalletSend money to your Zūm Wallet
WithdrawZumWalletWithdraw from your Zūm Wallet
AccountsPayableExecute accounts payable AP
AccountsReceivableExecute accounts receivable AR

Response

ParameterTypeDescription
IdguidTransaction id
CreatedAtdatetimeWhen the transaction was created
MemostringTransaction memo
CommentstringTransaction comment
AmountdecimalTransaction amount
CurrencystringTransaction currency
ZumRailsTypestringTransaction type
TransactionStatusstringIndicates the status of the transaction
FailedTransactionEventstringIf the transaction has failed, the transaction event that caused it (null otherwise)
ScheduledStartDatedateThe date on which the transaction will be sent to the financial institution
ClientTransactionIdstringThe Transaction id you informed in the creation of this transaction
FromstringFrom description for the transaction
TostringTo description for the transaction
FailedAtdatetimeWhen the transaction was failed (null otherwise)
TelecheckApprovalCodestringWhen the transaction method is ACH with provider Telecheck (null otherwise)
TelecheckDenialRecordNumberstringWhen the transaction method is ACH with provider Telecheck and the transaction was denied (null otherwise)
PaymentInstrumentIdstringPayment instrument id
CreditCardResponseCodestringResponse code when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CreditCardAdditionalResponseDatastringAdditional response data when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CustomerBasic Customer data
IdguidId for the related customer
CompanyNamestringCompany Name
UserIf transaction has a user - * Not all information from a user is returned in this endpoint
IdguidThe user id
First NamestringUser first name
Last NamestringUser last name
Company NamestringUser company name
IsActivebooleanIndicates if the user is active or not
WalletIf transaction has a wallet * Not all information from a user is returned in this endpoint
IdguidThe wallet id
TypestringThe wallet type
FundingSourceIf transaction has a funding source * Not all information from a user is returned in this endpoint
IdguidThe funding source id
InstitutionstringThe institution name
InstitutionNumberstringThe institution number
TransitNumberstringThe transit number
RoutingNumberstringThe account number
TargetWalletIf transaction has a target wallet
IdguidThe target wallet id
TypestringThe target wallet type
TransactionHistoryList of transaction history events
CreatedAtdatetimeWhen the transaction event happened
EventstringThe event that happened
EventDescriptionstringThe event description
info

When a transaction is created with a scheduled start date (delay transaction initiation), the transaction will be prepared to be sent to the financial institution according to its scheduled start date.

Testing transactions#

caution

In a sandbox environment, real bank operations are not performed.

To simulate a failure in a sandbox environment, use one of the keywords (shown below) in the COMMENT field while creating a transaction. If a COMMENT is not provided, or it does not match any of the keywords below, the transaction will eventually change status to "Completed".

Keywords to simulate a transaction failure

EventsLate Failure
AchFailedGeneralErrorno
AchFailedHighRiskOrPotentialFraudno
AchFailedDueToNegativeDatano
AchFailedDueToMerchantSetupno
AchFailedDueToProcessorTimeoutno
AchFailedTransactionExpiredno
AchFailedPaymentDeclinedByUserno
AchFailedTransactionNotAllowedno
AchFailedRejectedWithReasonyes
AchFailedReturnedOrClosedAccountyes
DebitCardFailedGeneralErrorn/a
DebitCardFailedPaymentDeclinedn/a
DebitCardFailedTransactionExpiredn/a
DebitCardFailedHighRiskOrPotentialFraudn/a
CreditCardInvalidRequestn/a
CreditCardRejectedByIssuingBankn/a
CreditCardExpiredCardn/a
CreditCardSuspectedFraudn/a
CreditCardTransactionNotPermittedn/a
CreditCardContactSupportn/a
CreditCardInvalidMerchantSetUpn/a
CreditCardSecurityViolationn/a
CreditCardInvalidCardOrDetailsn/a
CreditCardLostOrStolenCardn/a
CreditCardAccountClosedOrBlockedn/a
CreditCardDeemedHighRiskn/a
CreditCardUnknownResponseFromIssuingBankn/a
CreditCardCouldNotLocateOriginalTransactionn/a
CreditCardTransactionAlreadyReversedn/a
CreditCardGenericErrorn/a
CreditCardServiceUnavailablen/a
CreditCardRetryLatern/a
CreditCardReversalRejectedn/a
CreditCardDuplicateReversaln/a
CreditCardTransactionAlreadySettledn/a
CreditCardTimeoutReversaln/a
CreditCardDuplicateTransactionn/a
{
"ZumRailsType": "AccountPayable",
"TransactionMethod": "Ach",
"Amount": 123.45,
"Memo": "This transaction will succeed",
"Comment": "This transaction will succeed because there's no keyword",
"UserId": "1d431e8b-...85452adb4eee",
"WalletId": "8ebd932b-...b92633e14297"
}
tip

To simulate ACH transactions in sandbox, you need to add a bank account with a valid routing-number. The account-number can be any 9-12 digit number.

Some valid routing numbers that will work on the sandbox environment are:

  • 122000661
  • 026009593
  • 063100277
tip

To simulate Debit card transactions in sandbox, you need to add a debit card with a valid number.

Some valid debit card numbers that will work on the sandbox environment are:

  • 5102610000000077
  • 5102630000000026
  • 4000130000000106 ($0.00-$1000.00 - approval)

Get a specific transaction#

Use this endpoint to get information for a specific transaction. Provide the transaction id in the URL.

Method: GET

Endpoint: {{env}}/api/transaction/{transaction_id}

{
"statusCode": 200,
"message": "GET Request successful.",
"isError": false,
"result": {
"Id": "b7a8a505...364e8836404e",
"CreatedAt": "2020-05-13T17:59:47.039462",
"Memo": "Memo test",
"Comment": "This is a transaction to test",
"Amount": 123.45,
"Currency": "USD",
"TelecheckApprovalCode": "1228",
"PaymentInstrumentId": "8951e72a-....d334f07fe908",
"Customer": {
"Id": "e15bbe9b...dc256ba3a247",
"CompanyName": "Sam's Gym"
},
"User": {
"Id": "c11cc378...8f34ac8173be",
"FirstName": "John",
"LastName": "111",
"Email": "lxtkzblpk12wurb4tczfy@gmail.com",
"IsActive": true
},
"Wallet": {
"Id": "8ebd932b...b92633e14297",
"Type": "Unified",
"Currency": "USD"
},
"FundingSource": {
"Id": "1d431e8b...85452adb4eee",
"Institution": "Institution",
"InstitutionNumber": "123",
"RoutingNumber": "12345",
"AccountNumber": "1234567"
},
"TransactionHistory": [
{
"CreatedAt": "2020-05-13T17:59:47.284943",
"Event": "Started",
"EventDescription": "Transaction with type AccountsPayable started, from Funding Source to Zūm Wallet with amount: $123.45"
}
],
"ZumRailsType": "AccountsPayable",
"TransactionMethod": "Ach",
"TransactionStatus": "InProgress",
"From": "Zūm Wallet",
"To": "User john 111",
"FailedAt": null,
"PaymentInstrumentId": "92142401-d17e-4906-91e8-389ba0d87e75"
}
}

Response

ParameterTypeDescription
IdguidTransaction id
CreatedAtdatetimeWhen the transaction was created
MemostringTransaction memo
CommentstringTransaction comment
AmountdecimalTransaction amount
CurrencystringTransaction currency
ZumRailsTypestringTransaction type
TransactionStatusstringIndicates the status of the transaction
FailedTransactionEventstringIf the transaction has failed, the transaction event that caused it (null otherwise)
ScheduledStartDatedateThe date on which the transaction will be sent to the financial institution
ClientTransactionIdstringThe Transaction id you informed in the creation of this transaction
FromstringFrom description for the transaction
TostringTo description for the transaction
FailedAtdatetimeWhen the transaction was failed (null otherwise)
TelecheckApprovalCodestringWhen the transaction method is ACH with provider Telecheck (null otherwise)
TelecheckDenialRecordNumberstringWhen the transaction method is ACH with provider Telecheck and the transaction was denied (null otherwise)
PaymentInstrumentIdstringPayment instrument id
CreditCardResponseCodestringResponse code when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CreditCardAdditionalResponseDatastringAdditional response data when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CreditCardAuthorizationIdstringAuthorization id when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CreditCardAuthorizationNetworkIdstringAuthorization network id when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CreditCardAuthorizationNetworkNamestringAuthorization network name when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CreditCardErrorDatastringError message when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CustomerBasic Customer data
IdguidId for the related customer
CompanyNamestringCompany Name
UserIf transaction has a user - * Not all information from a user is returned in this endpoint
IdguidThe user id
First NamestringUser first name
Last NamestringUser last name
Company NamestringUser company name
IsActivebooleanIndicates if the user is active or not
WalletIf transaction has a wallet * Not all information from a user is returned in this endpoint
IdguidThe wallet id
TypestringThe wallet type
FundingSourceIf transaction has a funding source * Not all information from a user is returned in this endpoint
IdguidThe funding source id
InstitutionstringThe institution name
InstitutionNumberstringThe institution number
TransitNumberstringThe transit number
RoutingNumberstringThe account number
TargetWalletIf transaction has a target wallet
IdguidThe target wallet id
TypestringThe target wallet type
TransactionHistoryList of transaction history events
CreatedAtdatetimeWhen the transaction event happened
EventstringThe event that happened
EventDescriptionstringThe event description

Status and events#

Zūm Rails offers 6 main statuses for transactions:

Transaction Status

TypeDescription
InProgressIndicates the transaction is being processed
CompletedIndicates the transaction is completed.
FailedIndicates the transaction has failed, this is a permanent status.
Pending CancellationIndicates the transaction is pending cancellation.
CancelledIndicates the transaction has canceled, this is a permanent status.
ScheduledIndicates the transaction is scheduled.

Transaction Events

Zūm Rails also offers detailed transaction events that indicate every step the transaction lifecycle.

MethodEventDescription
AllStartedWhen the transaction started
AllSucceededWhen the transaction succeeds, when it finishes without any error
AllWalletFundedWhen the transaction funds a wallet
AllWalletWithdrawnWhen the transaction withdrawn a wallet
---------------------
ACHAchTransactionAcceptedWhen transaction is accepted
ACHAchFailedTransactionExpiredWhen transaction has expired
ACHAchFailedReturnedOrClosedAccountWhen transaction is returned due to a closed account or any other return reason
ACHAchFailedRejectedWithReasonWhen transaction is rejected for a reason
ACHAchFailedGeneralErrorWhen transaction has failed due to general error
ACHAchFailedHighRiskOrPotentialFraudWhen transaction is rejected as high-risk or potential fraud
ACHAchFailedDueToMerchantSetupWhen transaction failed because of invalid or inactive merchant id
ACHAchFailedInvalidValueForFieldWhen transaction failed due to invalid value for field
ACHAchFailedAuthorizationRevokedWhen transaction failed because authorization was revoked
ACHAchFailedDuplicateTransactionWhen transaction failed due to duplicated transaction
ACHAchFailedDueToProcessorTimeoutWhen transaction is not successfully processed due to processor timeout
ACHAchFailedTransactionNotAllowedWhen transaction is not allowed by provider
ACHAchDebitResponseReceivedWhen response is received for a debit transaction
ACHAchCreditResponseReceivedWhen response is received for a credit transaction
ACHAchTransactionReturnedWhen transaction returned from bank
ACHAchTransactionResubmittedWhen transaction is resubmitted for processing again
ACHAchCancellationFailedWhen request to cancel transaction failed
ACHAchCancellationFailedDueToMerchantSetupWhen request to cancel transaction failed due to merchant setup
ACHAchCancellationFailedRefundGreaterThanTransactionAmountWhen request to cancel transaction failed as refund amount is bigger than transaction amount
ACHAchCancellationFailedTransactionAlreadyCancelledWhen request to cancel transaction failed because transaction is already cancelled
ACHAchFailedDueToNegativeDataWhen transaction failed due to negative user data
ACHAchFailedIneligibleBankAccountWhen transaction failed because bank account is not on ACH network
---------------------
DebitCardDebitCardFailedGeneralErrorWhen transaction has failed due to general error
DebitCardDebitCardFailedPaymentDeclinedWhen transaction is declined by downstream issuer
DebitCardDebitCardFailedTransactionExpiredWhen transaction has expired
DebitCardDebitCardFailedHighRiskOrPotentialFraudWhen transaction is rejected as high-risk or potential fraud
---------------------
CreditCardCreditCardInvalidRequestWhen transaction has failed due to invalid request
CreditCardCreditCardRejectedByIssuingBankWhen transaction is rejected by issuing bank
CreditCardCreditCardExpiredCardWhen transaction has failed due to expired card
CreditCardCreditCardSuspectedFraudWhen transaction has failed due to suspected fraud
CreditCardCreditCardTransactionNotPermittedWhen transaction is not permitted
CreditCardCreditCardContactSupportWhen transaction has failed. Contact support
CreditCardCreditCardInvalidMerchantSetUpWhen transaction has failed due to invalid merchant setup
CreditCardCreditCardSecurityViolationWhen transaction has failed due to security violation
CreditCardCreditCardInvalidCardOrDetailsWhen transaction has failed due to invalid card or card details
CreditCardCreditCardLostOrStolenCardWhen transaction has failed due to lost ot stolen card
CreditCardCreditCardAccountClosedOrBlockedWhen transaction has failed due to account closed or blocked
CreditCardCreditCardDeemedHighRiskWhen transaction has failed due to deemed high risk
CreditCardCreditCardUnknownResponseFromIssuingBankWhen transaction has failed due to unknown response from issuing bank
CreditCardCreditCardCouldNotLocateOriginalTransactionWhen reversal transaction has failed due to could not locate original transaction
CreditCardCreditCardTransactionAlreadyReversedWhen reversal transaction has failed due to already reversed
CreditCardCreditCardGenericErrorWhen transaction has failed due to generic error
CreditCardCreditCardServiceUnavailableWhen transaction has failed due to service unavailable
CreditCardCreditCardRetryLaterWhen transaction has failed. Retry later
CreditCardCreditCardReversalRejectedWhen reversal transaction is rejected
CreditCardCreditCardDuplicateReversalWhen reversal transaction has failed due to duplicated
CreditCardCreditCardTransactionAlreadySettledWhen reversal transaction has failed due to already settled
CreditCardCreditCardTimeoutReversalWhen reversal transaction has failed due to timeout
CreditCardCreditCardDuplicateTransactionWhen transaction has failed due to duplicated

Search a transaction#

This endpoint will return transactions based on the filters applied. Transactions are returned with pagination, which means that if you need to retrieve all transactions you need to call the same endpoint incrementing the CurrentPage.

Method: POST

Endpoint: {{env}}/api/transaction/filter

{
"Id": "c7a8a909...364e8836409d",
"CreatedAtFrom": "2020-05-13T04:00:00.000Z",
"CreatedAtTo": "2020-05-13T04:00:00.000Z",
"CreatedAtOperator": "isBetween",
"UserId": "4085e4dc...20522aab5e1b",
"ZumRailsType": "AccountPayable",
"TransactionMethod": "Ach",
"TransactionStatus": "Failed",
"FailedTransactionEvent": "AchFailedPaymentDeclinedByUser",
"Pagination": {
"PageNumber": 1
}
}

Request parameters

ParameterTypeMandatoryDescription
IdguidnoTransaction id
GenericSearchstringnoFilter transactions by user name, user email, client transaction id, transaction id and memo
ZumRailsTypestringnoTransaction type
TransactionMethodstringnoThe transaction method
TransactionStatusstringnoTransaction status
FailedTransactionEventstringnoTransaction event (column Event from the "Transaction Events" table)
CreatedAtFromdatetimenoStart date (This field is only used when the operator is between)
CreatedAtTodatetimenoEnd date (This field is only used when the operator is between)
CreatedAtdatetimenoCreate date
CreatedAtOperatorstringnoOperator to filter with CreatedAt properties
UserIdstringnoUser id
ClientTransactionIdstringnoThe Transaction id you informed in the creation of the transaction
MemostringnoMemo field
CommentstringnoComment field
Paginationno
PageNumbernumbernoThe respective page, starting at 1

Response

ParameterTypeDescription
CurrentPagenumberThe current page
PageSizenumberThe amount of rows returned in the current page
TotalCountnumberThe total rows the filter returns
ItemsList of transactions
IdguidTransaction id
CreatedAtdatetimeWhen the transaction was created
MemostringTransaction memo
CommentstringTransaction comment
AmountdecimalTransaction amount
CurrencystringTransaction currency
ZumRailsTypestringTransaction type
TransactionMethodstringTransaction method
TransactionStatusstringIndicates the status of the transaction
FailedTransactionEventstringIf the transaction has failed, the transaction event that caused it (null otherwise)
ScheduledStartDatedateThe date on which the transaction will be sent to the financial institution
ClientTransactionIdstringThe Transaction id you informed in the creation of the transaction
TelecheckApprovalCodestringWhen the transaction method is ACH with provider Telecheck (null otherwise)
TelecheckDenialRecordNumberstringWhen the transaction method is ACH with provider Telecheck and the transaction was denied (null otherwise)
PaymentInstrumentIdstringPayment instrument id
tip

If you need to search for a specific transaction, we recommend you retrieve the transaction id and then use the GET specific transaction endpoint to retrieve the detailed information about the transaction.

Cancel a transaction#

Use this endpoint to cancel a specific transaction.

Method: DELETE

Endpoint: {{env}}/api/transaction/{transaction_id}

{
"statusCode": 200,
"message": "DELETE Request successful.",
"isError": false,
"result": "Request completed"
}
info
  • For credit card payment method, cancellation is allowed only on those transactions that have not been refunded.

Refund a Transaction#

With Zūm Rails, it is easy to refund Credit Card transactions. Currently we support whole/partial refunds of initial transactions. When you create a new refund, you must specify the transaction ID that you wish to refund. Creating a new refund will refund a transaction that has previously been created but not yet refunded. Funds will be refunded to the credit card that was originally charged.

Method: POST

Endpoint: {{env}}/api/transaction/{transaction_id}/refund

{
"statusCode": 200,
"message": "POST Request successful.",
"isError": false,
"result": {
"PaymentInstrumentId": "3394e27c...a3dba799bb0e",
"CreditCardResponseCode": "000",
"CreditCardAdditionalResponseData": "APPROVAL",
"Id": "57bad817...f883d1c133bd",
"CreatedAt": "2023-10-25T16:01:29.0270908Z",
"Memo": "Refund",
"Comment": "7c5af277-9509-44f8-a1e6-3e8c0c573992",
"Amount": 9.99,
"Customer": {
"Id": "e15bbe9b...dc256ba3a247",
"CompanyName": "Sam's Gym",
"CompanyEmail": "credit.card@zumrails.com"
},
"User": {
"Id": "c11cc378...8f34ac8173be",
"FirstName": "John",
"LastName": "111",
"Email": "lxtkzblpk12wurb4tczfy@gmail.com",
"IsActive": true,
"PaymentInstruments": [
{
"Id": "3394e27c...a3dba799bb0e"
}
]
},
"Wallet": {
"Id": "1790e62a...fda052b74341",
"Type": "Unified",
"Currency": "USD"
},
"ZumRailsType": "Refund",
"TransactionMethod": "CreditCard",
"TransactionHistory": [
{
"Id": "37a5b114-2164-4e0e-9605-316c5c6583c6",
"CreatedAt": "2023-10-25T16:01:29.1598149Z",
"Event": "Started",
"EventDescription": "Transaction with type Refund started, from Zūm Wallet to User John 111 - (************2446) with amount: $9.99"
},
{
"Id": "66b6db34-2264-48ba-99d3-99446c08c8ea",
"CreatedAt": "2023-10-25T16:01:33.1735111Z",
"Event": "WalletWithdrawn",
"EventDescription": "Wallet withdrawn, amount: $9.99"
},
{
"Id": "1bb732fc-843f-44bc-a570-85a375ac2136",
"CreatedAt": "2023-10-25T16:01:33.2034046Z",
"Event": "Succeeded",
"EventDescription": "Transaction completed"
}
],
"TransactionStatus": "Completed",
"From": "Zūm Wallet",
"To": "User John 111 - (************2446)",
"CompletedAt": "2022-07-19T16:57:50.2889607Z",
"Currency": "USD"
}
}
{
"Amount": 9.99
}

Response

Same response details of get transaction API.

Retrieve a refund#

To retrieve the details of an existing refund, use the get transaction API.

List all refunds#

Returns a list of all refunds you’ve previously created. The refunds are returned in sorted order, with the most recent refunds appearing first. For convenience, the 10 most recent refunds will be returned by default. To get a list of all refunds, use the filter transaction API.