Transfers

Transfer statuses

In the Orum system, a transfer can have one of the following statuses, indicated by the status field:

  • Created - A transfer was created.
  • Pending - A transfer is currently being processed by Orum.
  • Completed - A transfer request has been submitted to the payments network. This does not necessarily indicate a successful delivery of funds to the customer. Use the estimated_funds_delivery_date to know when the funds will land in the destination account.
  • Failed - A transfer failed. The failure could have occurred either in Orum's system or at the processor. Refer to the status_reason for more information.

The diagram below shows how a transfer can move through the above statuses. Note that a transfer can move from Completed to Failed if it was sent on the ACH network and a return occurs. To learn more about why a transfer is in the Failed state, refer to the status_reason field in the API response.

22962296

Status reasons

If a transfer fails, Orum will send a transfer_updated webhook. The transfer object in the payload will have a status of "failed" and a status_reasons array that explains why the transfer failed. status_reasons will contain a source and/or destination item, depending on where the transfer failure occurred.

status_reasons consist of:

  • reason_code a word-based code created by Orum to describe the reason for the failure. Orum reason codes are rail-agnostic.
  • reason_code_message a human-readable description of the reason code.
  • network_reason_code the reason code sent by the network (ex: R01)
  • network_reason_code_message the message sent by the network.
  • network_reason_code_rail_type the payment rail used in the transfer. Either RTP or ACH.

The network_reason_code and network_reason_message fields are populated with what Momentum receives from the network. That network information is mapped to an Orum-created reason_code and reason_code_message, which give a higher-level and more human-readable explanation of the transfer failure.

Sample webhook payload

{
    "event_id": "cl0e13b9-7311-440b-828a-a5c13c4e342p",
    "event_type": "transfer_updated",
    "created_at": "2022-08-26T18:57:18.087Z",
    "event_data": {
        "transfer": {
            "id": "542dbbe3-cf18-4d94-a490-7dde26f5b5bp",
            "transfer_reference_id": "970d9av1-3m96",
            "amount": 200,
            "currency": "USD",
            "speed": "same_day",
            "source": {
                "account_reference_id": "3c0699pw4-2e4091",
                "customer_reference_id": "9rs61-917dna80"
            },
            "destination": {
                "account_reference_id": "p7db1-2n38ywn",
                "customer_reference_id": "5jd29a-ja2qof612"
            },
            "status": "failed",
            "status_reasons": [
                {
                    "destination": {
                        "reason_code": "unexpected_error",
                        "reason_code_message": "There was an unexpected error with this transfer request",
                        "network_reason_code": "IN03",
                        "network_reason_code_message": "The payment could not be processed at this time due to an unexpected error, please try again later.",
                        "network_reason_code_rail_type": "RTP"
                    },
                    "source": {
                        "reason_code": "insufficient_funds",
                        "reason_code_message": "There was not enough money available to complete the transfer request",
                        "network_reason_code": "AM04",
                        "network_reason_code_message": "R01 INSUFFICENT FUNDS",
                        "network_reason_code_rail_type": "ACH"
                    }
                }
            ]
        }
    }
}

Possible status reasons

reason_codereason_code_message
blocked_accountAn account in the transfer request was blocked or prohibits posting of transfers against it
closed_accountAccount number specified has been closed on the bank of account's books
debit_blockedThe account owner has placed a stop payment on their account
deceased_partyOne of the parties in the transfer request was deceased
duplicated_transferDuplicate of a previous transfer request
insufficient_fundsThere was not enough money available to complete the transfer request
invalid_accountThe account number provided is invalid or does not exist
invalid_amountThe amount provided in the transfer request was invalid or missing
invalid_country_codeThe country code utilized was invalid
invalid_currencyThe currency provided in the transfer request was invalid or missing
invalid_fieldThere was erroneous, invalid, or missing data in the transfer request
invalid_routingThe routing number provided is invalid or does not exist
regulatory_errorThe transfer could not be completed because of limitations imposed by a regulator
transfer_on_holdTransfer request was questionable or part of anomalous activity
unauthorized_transferA party in the transfer request was either unknown or did not authorize this request
unavailable_financial_institutionSending or receiving financial institution is currently not available or does not support this request type
unexpected_errorThere was an unexpected error with this transfer request
unsupported_transferTransfer type is not supported or forbidden

Transfer speeds

When you create a transfer, the speed parameter will impact how quickly funds will arrive in the destination account. The table below shows the correlation between the speed requested and the funds delivery time per use case.

Note: the funds delivery times in the above table assume transfer requests are received by the cutoff time. If a transfer request is received after the cutoff time, an extra business day will be added to the funds delivery time.

22342234

Reference transfer speeds

Estimated funds delivery date

Momentum uses the estimated_funds_delivery_date to update you on when the funds are predicted to settle in the destination account. Once Momentum has calculated the date, a transfer_updated webhook will be fired and the payload will contain estimated_funds_delivery_date. estimated_funds_delivery_date will also be present in the GET /transfers/{id} and GET /transfers API responses.

{
    "event_id": "30136439-2e46-4240-a3mc-d46ca9ffb46s",
    "event_type": "transfer_updated",
    "created_at": "2022-09-14T21:58:43.877Z",
    "event_data": {
        "transfer": {
            "id": "ab53a6f0-ea6f-4753-853d-8f944cadcba5",
            "amount": 400,
            "transfer_reference_id": "d7pd620d-v2ba1-44n2",
            "currency": "USD",
            "speed": "same_day",
            "status": "pending",
            "estimated_funds_delivery_date": "2022-09-17T00:00:00Z",
            "account_statement_descriptor": "Account to account transfer",
            "created_at": "2022-09-14T20:58:19.256831Z",
            "updated_at": "2022-09-14T21:58:24.205573Z",
            "source": {
                "account_reference_id": "3c0699pw4-2e4091",
                "customer_reference_id": "9rs61-917dna80"
            },
            "destination": {
                "account_reference_id": "p7db1-2n38ywn",
                "customer_reference_id": "5jd29a-ja2qof612"
            }
        }
    }
 }