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

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

Request (ACH)

{

"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 (Debit Card)

{

"ZumRailsType": "AccountsPayable",

"TransactionMethod": "DebitCard",

"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 (Credit Card)

{

"ZumRailsType": "AccountsReceivable",

"TransactionMethod": "CreditCard",

"Amount": 123.45,

"Memo": "Memo",

"Comment": "This transaction is just a test from a user to wallet",

"UserId": "1d431e8b-...85452adb4eee",

"WalletId": "8ebd932b-...b92633e14297",

"PaymentInstrumentId": "92142401-...389ba0d87e75"

}

Request (Money Transfer)

{

"ZumRailsType": "AccountsReceivable",

"TransactionMethod": "MoneyTransfer",

"Amount": 123.45,

"Memo": "Memo",

"Comment": "This transaction is just a test from a user to wallet",

"UserId": "1d431e8b-...85452adb4eee",

"WalletId": "8ebd932b-...b92633e14297",

"PaymentInstrumentId": "92142401-...389ba0d87e75"

}

Response

{

"statusCode": 200,

"message": "POST Request successful.",

"isError": false,

"result": {

"Id": "0bc9894d-...f691024aca19",

"Amount": 123.45,

"Comment": "This transaction is just a test from a wallet to user",

"TransactionMethod": "Ach",

"TransactionStatus": "InProgress",

"Customer": {

"Id": "911388da-5095-4cc9-bf51-cf636dd6c46b",

"CompanyName": "US Company",

"CompanyEmail": "uscompany@zumrails.com"

},

"ZumRailsType": "AccountsReceivable",

"PaymentInstrumentId": "8951e72a-...d334f07fe908",

"CreditCardResponseCode": "000",

"CreditCardAdditionalResponseData": "APPROVAL",

"User": {

"Id": "8bad268a-5a76-4d59-8cc9-83e8e6cedfd1",

"FirstName": "Jane",

"LastName": "Smith",

"Email": "jane.smith@example.com"

},

"Wallet": {

"Id": "1662f74a-...d8b966ac7198",

"Type": "Unified",

"Currency": "USD"

},

"From": "Jane Smith - jane.smith@example.com",

"Memo": "Memo",

"To": "Zūm Wallet",

"Currency": "USD",

"CreatedAt": "2023-07-14T21:20:20.4715365Z",

"TransactionHistory": [{

{

"Id": "1177131e-...d5a30d1f40ba",

"CreatedAt": "2023-07-14T21:20:20.7628922Z",

"Event": "Started",

"EventDescription": "Transaction with type AccountsReceivable started, from Jane Smith - jane.smith@example.com to Zūm Wallet with amount: $123.45"

},

}]

}

}

Request parameters

Parameter	Type	Mandatory	Description
ZumRailsType	string	yes	Transaction type
TransactionMethod	string	yes	Transaction method.
Amount	decimal	yes	Transaction amount
Memo	string	yes	Memo description.
Comment	string	no	Internal comment you might want to add.
FundingSourceId	guid	no	Funding Source Id
WalletId	guid	no	Wallet Id
UserId	guid	no	User Id
PaymentInstrumentId	string	yes	Payment instrument id
User	User input	no	It'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.
ScheduledStartDate	date	no	The date when the transaction will be sent to the financial institution, in the format YYYY-MM-DD. Must be greater than today.
ClientTransactionId	string	no	This field can be used to store the Transaction id created in your system when the Transaction is initiated

TransactionMethod

Method	Description
Ach	ACH transaction
DebitCard	Debit card transaction
CreditCard	Credit card transaction
MoneyTransfer	MoneyTransfer transaction

ZumRailsType

Type	Description
FundZumWallet	Send money to your Zūm Wallet
WithdrawZumWallet	Withdraw from your Zūm Wallet
AccountsPayable	Execute accounts payable AP
AccountsReceivable	Execute accounts receivable AR

Response

Parameter	Type	Description
Id	guid	Transaction id
CreatedAt	datetime	When the transaction was created
Memo	string	Transaction memo
Comment	string	Transaction comment
Amount	decimal	Transaction amount
Currency	string	Transaction currency
ZumRailsType	string	Transaction type
TransactionStatus	string	Indicates the status of the transaction
FailedTransactionEvent	string	If the transaction has failed, the transaction event that caused it (null otherwise)
ScheduledStartDate	date	The date on which the transaction will be sent to the financial institution
ClientTransactionId	string	The Transaction id you informed in the creation of this transaction
From	string	From description for the transaction
To	string	To description for the transaction
FailedAt	datetime	When the transaction was failed (null otherwise)
TelecheckApprovalCode	string	When the transaction method is ACH with provider Telecheck (null otherwise)
TelecheckDenialRecordNumber	string	When the transaction method is ACH with provider Telecheck and the transaction was denied (null otherwise)
PaymentInstrumentId	string	Payment instrument id
CreditCardResponseCode	string	Response code when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CreditCardAdditionalResponseData	string	Additional response data when the transaction method is Credit Card with provider RapidConnect (null otherwise)
Customer		Basic Customer data
Id	guid	Id for the related customer
CompanyName	string	Company Name
User		If transaction has a user - * Not all information from a user is returned in this endpoint
Id	guid	The user id
First Name	string	User first name
Last Name	string	User last name
Company Name	string	User company name
IsActive	boolean	Indicates if the user is active or not
Wallet		If transaction has a wallet * Not all information from a user is returned in this endpoint
Id	guid	The wallet id
Type	string	The wallet type
FundingSource		If transaction has a funding source * Not all information from a user is returned in this endpoint
Id	guid	The funding source id
Institution	string	The institution name
InstitutionNumber	string	The institution number
TransitNumber	string	The transit number
RoutingNumber	string	The account number
TargetWallet		If transaction has a target wallet
Id	guid	The target wallet id
Type	string	The target wallet type
TransactionHistory		List of transaction history events
CreatedAt	datetime	When the transaction event happened
Event	string	The event that happened
EventDescription	string	The 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

Events	Late Failure
AchFailedGeneralError	no
AchFailedHighRiskOrPotentialFraud	no
AchFailedDueToNegativeData	no
AchFailedDueToMerchantSetup	no
AchFailedDueToProcessorTimeout	no
AchFailedTransactionExpired	no
AchFailedPaymentDeclinedByUser	no
AchFailedTransactionNotAllowed	no
AchFailedRejectedWithReason	yes
AchFailedReturnedOrClosedAccount	yes
DebitCardFailedGeneralError	n/a
DebitCardFailedPaymentDeclined	n/a
DebitCardFailedTransactionExpired	n/a
DebitCardFailedHighRiskOrPotentialFraud	n/a
CreditCardInvalidRequest	n/a
CreditCardRejectedByIssuingBank	n/a
CreditCardExpiredCard	n/a
CreditCardSuspectedFraud	n/a
CreditCardTransactionNotPermitted	n/a
CreditCardContactSupport	n/a
CreditCardInvalidMerchantSetUp	n/a
CreditCardSecurityViolation	n/a
CreditCardInvalidCardOrDetails	n/a
CreditCardLostOrStolenCard	n/a
CreditCardAccountClosedOrBlocked	n/a
CreditCardDeemedHighRisk	n/a
CreditCardUnknownResponseFromIssuingBank	n/a
CreditCardCouldNotLocateOriginalTransaction	n/a
CreditCardTransactionAlreadyReversed	n/a
CreditCardGenericError	n/a
CreditCardServiceUnavailable	n/a
CreditCardRetryLater	n/a
CreditCardReversalRejected	n/a
CreditCardDuplicateReversal	n/a
CreditCardTransactionAlreadySettled	n/a
CreditCardTimeoutReversal	n/a
CreditCardDuplicateTransaction	n/a
MoneyTransferAccountBlockForMerchant	n/a
MoneyTransferAccountClosedOrBlocked	n/a
MoneyTransferContactSupport	n/a
MoneyTransferDeemedHighRisk	n/a
MoneyTransferDuplicateTransaction	n/a
MoneyTransferExceed24HoursLimitForMerchant	n/a
MoneyTransferExceed24HoursLimitForUser	n/a
MoneyTransferExceed30DaysLimitForMerchant	n/a
MoneyTransferExceed30DaysLimitForUser	n/a
MoneyTransferExceed7DaysLimitForMerchant	n/a
MoneyTransferExceed7DaysLimitForUser	n/a
MoneyTransferExceedsLimits	n/a
MoneyTransferExceedsMonthlyLimits	n/a
MoneyTransferExceedsWithdrawalFrequencyLimit	n/a
MoneyTransferExpiredCard	n/a
MoneyTransferGenericError	n/a
MoneyTransferInvalidAmount	n/a
MoneyTransferInvalidCardOrDetails	n/a
MoneyTransferInvalidMerchantSetUp	n/a
MoneyTransferInvalidRequest	n/a
MoneyTransferLostOrStolenCard	n/a
MoneyTransferRejectedByIssuingBank	n/a
MoneyTransferRetryLater	n/a
MoneyTransferSecurityViolation	n/a
MoneyTransferServiceUnavailable	n/a
MoneyTransferSuspectedFraud	n/a
MoneyTransferTransactionNotPermitted	n/a
MoneyTransferUnknownResponseFromIssuingBank	n/a
MoneyTransferWithdrawalAmountLimit	n/a
MoneyTransferDuplicateReversal	n/a
MoneyTransferReversalRejected	n/a
MoneyTransferTransactionAlreadyReversed	n/a
MoneyTransferTransactionAlreadySettled	n/a
MoneyTransferCouldNotLocateOriginalTransaction	n/a
MoneyTransferReversalFailed	n/a

Success

{

"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"

}

Failure

{

"ZumRailsType": "AccountPayable",

"TransactionMethod": "Ach",

"Amount": 123.45,

"Memo": "This transaction will fail with event AchFailedGeneralError",

"Comment": "AchFailedGeneralError",

"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 5-17 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}

Response

{

"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"

},

"TransactionChargeback": [

{

"Id": "e5ec36c3...5445500db505"

"AcquirerReferenceNumber" : "1674915201620667421592979",

"AuthorizationCode" : "OK5234",

"ChargebackAmount" : 9.91,

"ChargebackControlNumber" : "771638347",

"ChargebackStatus" : "Disputed",

"ChargebackWorkTypeCode" : "1",

"DisputeCurrencyCode" : "USD",

"DisputeReasonCode" : "1350",

"DueDate" : "2024-04-14",

"FileId" : "685221186",

"MemberMessageText" : "Misrepresentation",

"ReceivedDate" : "2024-04-10",

}

]

"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

Parameter	Type	Description
Id	guid	Transaction id
CreatedAt	datetime	When the transaction was created
Memo	string	Transaction memo
Comment	string	Transaction comment
Amount	decimal	Transaction amount
Currency	string	Transaction currency
ZumRailsType	string	Transaction type
TransactionStatus	string	Indicates the status of the transaction
FailedTransactionEvent	string	If the transaction has failed, the transaction event that caused it (null otherwise)
ScheduledStartDate	date	The date on which the transaction will be sent to the financial institution
ClientTransactionId	string	The Transaction id you informed in the creation of this transaction
From	string	From description for the transaction
To	string	To description for the transaction
FailedAt	datetime	When the transaction was failed (null otherwise)
TelecheckApprovalCode	string	When the transaction method is ACH with provider Telecheck (null otherwise)
TelecheckDenialRecordNumber	string	When the transaction method is ACH with provider Telecheck and the transaction was denied (null otherwise)
PaymentInstrumentId	string	Payment instrument id
CreditCardResponseCode	string	Response code when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CreditCardAdditionalResponseData	string	Additional response data when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CreditCardAuthorizationId	string	Authorization id when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CreditCardAuthorizationNetworkId	string	Authorization network id when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CreditCardAuthorizationNetworkName	string	Authorization network name when the transaction method is Credit Card with provider RapidConnect (null otherwise)
CreditCardErrorData	string	Error message when the transaction method is Credit Card with provider RapidConnect (null otherwise)
Customer		Basic Customer data
Id	guid	Id for the related customer
CompanyName	string	Company Name
User		If transaction has a user - * Not all information from a user is returned in this endpoint
Id	guid	The user id
First Name	string	User first name
Last Name	string	User last name
Company Name	string	User company name
IsActive	boolean	Indicates if the user is active or not
Wallet		If transaction has a wallet * Not all information from a user is returned in this endpoint
Id	guid	The wallet id
Type	string	The wallet type
FundingSource		If transaction has a funding source * Not all information from a user is returned in this endpoint
Id	guid	The funding source id
Institution	string	The institution name
InstitutionNumber	string	The institution number
TransitNumber	string	The transit number
RoutingNumber	string	The account number
TargetWallet		If transaction has a target wallet
Id	guid	The target wallet id
Type	string	The target wallet type
TransactionChargeback		List of transaction chargebacks
Id	guid	The transaction chargeback id
AcquirerReferenceNumber	string	Reference number associated with the inquiry
AuthorizationCode	string	Authorization code from association(s)
ChargebackAmount	decimal	Chargeback amount
ChargebackControlNumber	string	Chargeback control number
ChargebackStatus	string	Chargeback status
ChargebackWorkTypeCode	string	Chargeback work type code
DisputeCurrencyCode	string	Dispute currency code
DisputeReasonCode	string	Dispute reason code
DueDate	string	Due date (format "yyyy-MM-dd)
FileId	string	File id
MemberMessageText	string	Member message text
ReceivedDate	string	Received date (format "yyyy-MM-dd)
TransactionHistory		List of transaction history events
CreatedAt	datetime	When the transaction event happened
Event	string	The event that happened
EventDescription	string	The event description

Status and events

Zūm Rails offers 6 main statuses for transactions:

Transaction Status

Type	Description
InProgress	Indicates the transaction is being processed
Completed	Indicates the transaction is completed.
Failed	Indicates the transaction has failed, this is a permanent status.
Pending Cancellation	Indicates the transaction is pending cancellation.
Cancelled	Indicates the transaction has canceled, this is a permanent status.
Scheduled	Indicates the transaction is scheduled.

Transaction Events

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

Method	Event	Description
All	Started	When the transaction started
All	Succeeded	When the transaction succeeds, when it finishes without any error
All	WalletFunded	When the transaction funds a wallet
All	WalletWithdrawn	When the transaction withdrawn a wallet
-------	-------	-------
ACH	AchTransactionAccepted	When transaction is accepted
ACH	AchFailedTransactionExpired	When transaction has expired
ACH	AchFailedReturnedOrClosedAccount	When transaction is returned due to a closed account or any other return reason
ACH	AchFailedRejectedWithReason	When transaction is rejected for a reason
ACH	AchFailedGeneralError	When transaction has failed due to general error
ACH	AchFailedHighRiskOrPotentialFraud	When transaction is rejected as high-risk or potential fraud
ACH	AchFailedDueToMerchantSetup	When transaction failed because of invalid or inactive merchant id
ACH	AchFailedInvalidValueForField	When transaction failed due to invalid value for field
ACH	AchFailedAuthorizationRevoked	When transaction failed because authorization was revoked
ACH	AchFailedDuplicateTransaction	When transaction failed due to duplicated transaction
ACH	AchFailedDueToProcessorTimeout	When transaction is not successfully processed due to processor timeout
ACH	AchFailedTransactionNotAllowed	When transaction is not allowed by provider
ACH	AchDebitResponseReceived	When response is received for a debit transaction
ACH	AchCreditResponseReceived	When response is received for a credit transaction
ACH	AchTransactionReturned	When transaction returned from bank
ACH	AchTransactionResubmitted	When transaction is resubmitted for processing again
ACH	AchCancellationFailed	When request to cancel transaction failed
ACH	AchCancellationFailedDueToMerchantSetup	When request to cancel transaction failed due to merchant setup
ACH	AchCancellationFailedRefundGreaterThanTransactionAmount	When request to cancel transaction failed as refund amount is bigger than transaction amount
ACH	AchCancellationFailedTransactionAlreadyCancelled	When request to cancel transaction failed because transaction is already cancelled
ACH	AchFailedDueToNegativeData	When transaction failed due to negative user data
ACH	AchFailedIneligibleBankAccount	When transaction failed because bank account is not on ACH network
-------	-------	-------
DebitCard	DebitCardFailedGeneralError	When transaction has failed due to general error
DebitCard	DebitCardFailedPaymentDeclined	When transaction is declined by downstream issuer
DebitCard	DebitCardFailedTransactionExpired	When transaction has expired
DebitCard	DebitCardFailedHighRiskOrPotentialFraud	When transaction is rejected as high-risk or potential fraud
-------	-------	-------
CreditCard	CreditCardInvalidRequest	When transaction has failed due to invalid request
CreditCard	CreditCardRejectedByIssuingBank	When transaction is rejected by issuing bank
CreditCard	CreditCardExpiredCard	When transaction has failed due to expired card
CreditCard	CreditCardSuspectedFraud	When transaction has failed due to suspected fraud
CreditCard	CreditCardTransactionNotPermitted	When transaction is not permitted
CreditCard	CreditCardContactSupport	When transaction has failed. Contact support
CreditCard	CreditCardInvalidMerchantSetUp	When transaction has failed due to invalid merchant setup
CreditCard	CreditCardSecurityViolation	When transaction has failed due to security violation
CreditCard	CreditCardInvalidCardOrDetails	When transaction has failed due to invalid card or card details
CreditCard	CreditCardLostOrStolenCard	When transaction has failed due to lost ot stolen card
CreditCard	CreditCardAccountClosedOrBlocked	When transaction has failed due to account closed or blocked
CreditCard	CreditCardDeemedHighRisk	When transaction has failed due to deemed high risk
CreditCard	CreditCardUnknownResponseFromIssuingBank	When transaction has failed due to unknown response from issuing bank
CreditCard	CreditCardCouldNotLocateOriginalTransaction	When reversal transaction has failed due to could not locate original transaction
CreditCard	CreditCardTransactionAlreadyReversed	When reversal transaction has failed due to already reversed
CreditCard	CreditCardGenericError	When transaction has failed due to generic error
CreditCard	CreditCardServiceUnavailable	When transaction has failed due to service unavailable
CreditCard	CreditCardRetryLater	When transaction has failed. Retry later
CreditCard	CreditCardReversalRejected	When reversal transaction is rejected
CreditCard	CreditCardDuplicateReversal	When reversal transaction has failed due to duplicated
CreditCard	CreditCardTransactionAlreadySettled	When reversal transaction has failed due to already settled
CreditCard	CreditCardTimeoutReversal	When reversal transaction has failed due to timeout
CreditCard	CreditCardDuplicateTransaction	When transaction has failed due to duplicated
-------	-------	-------
MoneyTransfer	MoneyTransferAccountBlockForMerchant	When transaction has failed due to account blocked for merchant
MoneyTransfer	MoneyTransferAccountClosedOrBlocked	When transaction has failed due to account closed or blocked
MoneyTransfer	MoneyTransferContactSupport	When transaction has failed. Contact support
MoneyTransfer	MoneyTransferDeemedHighRisk	When transaction has failed due to deemed high risk
MoneyTransfer	MoneyTransferDuplicateTransaction	When transaction has failed due to duplicated
MoneyTransfer	MoneyTransferExceed24HoursLimitForMerchant	When transaction has failed due to exceeded preset 24-hour transaction count or amount limit for merchant.
MoneyTransfer	MoneyTransferExceed24HoursLimitForUser	When transaction has failed due to exceeded preset 24-hour transaction count or amount limit for user.
MoneyTransfer	MoneyTransferExceed30DaysLimitForMerchant	When transaction has failed due to exceeded preset 30-day transaction count or amount limit for merchant.
MoneyTransfer	MoneyTransferExceed30DaysLimitForUser	When transaction has failed due to exceeded preset 30-day transaction count or amount limit for user.
MoneyTransfer	MoneyTransferExceed7DaysLimitForMerchant	When transaction has failed due to exceeded preset 7-day transaction count or amount limit for merchant.
MoneyTransfer	MoneyTransferExceed7DaysLimitForUser	When transaction has failed due to exceeded preset 7-day transaction count or amount limit for user.
MoneyTransfer	MoneyTransferExceedsLimits	When transaction has failed due to exceeds limit
MoneyTransfer	MoneyTransferExceedsMonthlyLimits	When transaction has failed due to exceeds monthly limit
MoneyTransfer	MoneyTransferExceedsWithdrawalFrequencyLimit	When transaction has failed due to exceeds withdrawal frequency limit
MoneyTransfer	MoneyTransferExpiredCard	When transaction has failed due to expired card
MoneyTransfer	MoneyTransferGenericError	When transaction has failed due to generic error
MoneyTransfer	MoneyTransferInvalidAmount	When transaction has failed due to account blocked for merchant
MoneyTransfer	MoneyTransferInvalidCardOrDetails	When transaction has failed due to invalid card or card details
MoneyTransfer	MoneyTransferInvalidMerchantSetUp	When transaction has failed due to invalid merchant setup
MoneyTransfer	MoneyTransferInvalidRequest	When transaction has failed due to invalid request
MoneyTransfer	MoneyTransferLostOrStolenCard	When transaction has failed due to lost ot stolen card
MoneyTransfer	MoneyTransferRejectedByIssuingBank	When transaction is rejected by issuing bank
MoneyTransfer	MoneyTransferRetryLater	When transaction has failed. Retry later
MoneyTransfer	MoneyTransferSecurityViolation	When transaction has failed due to security violation
MoneyTransfer	MoneyTransferServiceUnavailable	When transaction has failed due to service unavailable
MoneyTransfer	MoneyTransferSuspectedFraud	When transaction has failed due to suspected fraud
MoneyTransfer	MoneyTransferTransactionNotPermitted	When transaction is not permitted
MoneyTransfer	MoneyTransferUnknownResponseFromIssuingBank	When transaction has failed due to unknown response from issuing bank
MoneyTransfer	MoneyTransferWithdrawalAmountLimit	When transaction has failed due to exceeds withdrawal amount limit
MoneyTransfer	MoneyTransferInitiated	When transaction is send to the bank
MoneyTransfer	MoneyTransferAuthorized	When transaction is authorized by the bank
MoneyTransfer	MoneyTransferVoidOrReversalInitiated	When transaction cancellation is initiated
MoneyTransfer	MoneyTransferVoidedOrFullyReversed	When transaction cancellation is confirmed
MoneyTransfer	MoneyTransferVoidedOrFullyReversedDueToSuspectedFraud	When transaction cancellation is confirmed due to suspicion of fraud
MoneyTransfer	MoneyTransferDuplicateReversal	When transaction cancellation is not authorized due to duplication
MoneyTransfer	MoneyTransferReversalRejected	When transaction cancellation is not authorized
MoneyTransfer	MoneyTransferTransactionAlreadyReversed	When transaction is already cancelled
MoneyTransfer	MoneyTransferTransactionAlreadySettled	When transaction cancellation is not authorized due to funds already being settled
MoneyTransfer	MoneyTransferCouldNotLocateOriginalTransaction	When transaction cancellation is not authorized due to not being able to locate transaction
MoneyTransfer	MoneyTransferReversalFailed	When transaction cancellation failed due to a error
MoneyTransfer	MoneyTransferTransactionAlreadyRefunded	When transaction is already refunded
MoneyTransfer	MoneyTransferRefundNotToOriginalCreditCard	When transaction has failed due to refund not being issued to the original credit card.

Transaction Chargeback Status

Type	Description
Pending	Indicates the chargeback is pending to take action.
AcceptedByUser	Indicates the chargeback was accepted by user via portal or API.
AcceptedByDefault	Indicates the chargeback was accepted past due date.
Disputed	Indicates the chargeback was disputed by user via portal our API.

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

Request

{

"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

}

}

Response

{

"statusCode": 200,

"message": "POST Request successful.",

"isError": false,

"result": {

"CurrentPage": 1,

"PageSize": 1,

"TotalCount": 2,

"Items": [

{

"Id": "b7a8a505...364e8836404e",

"CreatedAt": "2020-05-13T17:59:47.039462",

"Memo": "Memo test",

"Comment": "This is a transaction to test the platform",

"Amount": 123.45,

"Currency": "USD",

"ZumRailsType": "AccountPayable",

"TransactionMethod": "Ach",

"TransactionStatus": "Failed",

"FailedTransactionEvent": "AchFailedPaymentDeclinedByUser",

"PaymentInstrumentId": "92142401-d17e-4906-91e8-389ba0d87e75"

},

{

"Id": "c8a8a505...364e8836405f",

"CreatedAt": "2020-05-13T17:59:47.039462",

"Memo": "Memo test",

"Comment": "This is a transaction to test the platform",

"Amount": 123.45,

"Currency": "USD",

"ZumRailsType": "AccountPayable",

"TransactionMethod": "Ach",

"TransactionStatus": "Failed",

"FailedTransactionEvent": "AchFailedPaymentDeclinedByUser",

"PaymentInstrumentId": "864595-d17e-4906-91e8-389ba0d87e88"

}

]

}

}

Request parameters

Parameter	Type	Mandatory	Description
Id	guid	no	Transaction id
GenericSearch	string	no	Filter transactions by user name, user email, client transaction id, transaction id and memo
ZumRailsType	string	no	Transaction type
TransactionMethod	string	no	The transaction method
TransactionStatus	string	no	Transaction status
FailedTransactionEvent	string	no	Transaction event (column Event from the "Transaction Events" table)
DateType	string	no	The type of date on which the date-filter applies.
CreatedAtFrom	datetime	no	Start date (This field is only used when the operator is between)
CreatedAtTo	datetime	no	End date (This field is only used when the operator is between)
CreatedAt	datetime	no	Created date
CreatedAtOperator	string	no	Operator to filter with CreatedAt properties
UserId	string	no	User id
ClientTransactionId	string	no	The Transaction id you informed in the creation of the transaction
ChargebackAction	string	no	Transaction chargeback status
Memo	string	no	Memo field
Comment	string	no	Comment field
Pagination		no
PageNumber	number	no	The respective page, starting at 1

Date Operators

Type	Description
IsInTheLast	Filter records on or after
ExactlyMatches	Filter records with exact date
IsBetween	Filters records in range
IsAfter	Filter records after date
IsOnOrAfter	Filter records on or after
IsBefore	Filter records before date
IsBeforeOrOn	Filter records before or on date

Date Types

Type	Description
CreatedAt	Filter records based on date when transactions were created
CompletedAt	Filter records based on date when transactions were completed
CancelledAt	Filters records based on date when transactions were cancelled
FailedAt	Filter records based on date when transactions were failed

Response

Parameter	Type	Description
CurrentPage	number	The current page
PageSize	number	The amount of rows returned in the current page
TotalCount	number	The total rows the filter returns
Items		List of transactions
Id	guid	Transaction id
CreatedAt	datetime	When the transaction was created
Memo	string	Transaction memo
Comment	string	Transaction comment
Amount	decimal	Transaction amount
Currency	string	Transaction currency
ZumRailsType	string	Transaction type
TransactionMethod	string	Transaction method
TransactionStatus	string	Indicates the status of the transaction
FailedTransactionEvent	string	If the transaction has failed, the transaction event that caused it (null otherwise)
ScheduledStartDate	date	The date on which the transaction will be sent to the financial institution
ClientTransactionId	string	The Transaction id you informed in the creation of the transaction
TelecheckApprovalCode	string	When the transaction method is ACH with provider Telecheck (null otherwise)
TelecheckDenialRecordNumber	string	When the transaction method is ACH with provider Telecheck and the transaction was denied (null otherwise)
PaymentInstrumentId	string	Payment 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}

Response

{

"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

Response

{

"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"

}

}

Payload

{

"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.

Chargeback

Chargeback applies only for credit card transactions and it can be accepted or disputed by the user until the due date. After the chargeback due date passes, the chargeback is accepted by default.

Accept Chargeback

Use this endpoint to accept a specific chargeback for a credit card transaction.

Method: PATCH

Endpoint: {{env}}/api/TransactionChargeback/{{TransactionChargebackId}}/accept

Response

{

"statusCode": 200,

"message": "PATCH Request successful.",

"isError": false,

"result": "Request completed"

}

info

• The TransactionChargebackId information can be retrieved through the Get a specific transaction endpoint.
• If chargeback is not accepted or disputed until the due date, the chargeback will be automatically accepted.
• A chargeback cannot be accepted if it is already accepted or disputed or is past due date.

Dispute Chargeback

Use this endpoint to dispute a specific chargeback for a credit card transaction.

Method: PATCH

Endpoint: {{env}}/api/TransactionChargeback/{{TransactionChargebackId}}/dispute

Response

{

"statusCode": 200,

"message": "PATCH Request successful.",

"isError": false,

"result": "Request completed"

}

info

• The TransactionChargebackId information can be retrieved through the Get a specific transaction endpoint.
• A chargeback cannot be disputed if it is already accepted or disputed or is past due date.