Retrieve an existing sellorder

A sellorder represents a cashout, wherein users can send funds from their Coins wallet account to a preferred cashout option.

Lifecycle of a cash out

A cash out undergoes several phases before cash is delivered to the recipient. The first stage is creating the sell order. At this stage, a sender's order will be funded by debiting his Coins wallet account. Once the funds are received by Coins, the cash out will proceed to a delivery stage. Finally, a cash out may either have a successful delivery or a failed delivery. In the event of a failed delivery, funds will be refunded back to the sender.

Sending funds to Coins

The status property of a cash out shows whether the funds from the sender are already received by coins. It may have one of the three following values:

  • pending - The payment is yet to be received from the sender.
  • success - Payment for the cash out was successfully received by coins.
  • failed - The maximum allowed time window to pay for the cash out has been reached. A cash out with a failed status is already expired and any funds sent to pay for the cash out will no longer transition the payment status.

Furthermore, the delivery_status property provides a more granular view of the current order state. The following are its possible values:

  • pending_payment - The order has been initiated, but payment has not yet been received
  • payment_received - We have successfully received your payment, and will be processed accordingly
  • expired - The order has expired because the payment has not been received on time
  • on_hold - The order is currently being held temporarily, and is being reviewed on our end
  • delivering - The order is en route to your recipient, or is ready for claiming by your customer
  • settlement_failed - A settlement method for the order has failed. At this stage, we may still attempt to process the order through other methods. If there are no other options to settle, the order will be processed for refund.
  • refunding - We’re in the process of refunding the payment to your account
  • refunded - The money has been returned to your account
  • settled - The payment for the order has been successfully completed

Aside from status and delivery_status, the received payments can also be seen in the payments property, which is an array of all the payments received for the cash out. A payment has the following properties:

  • transaction_type - Indicates whether the payment was from an external blockchain transaction, or an internal Coins transaction. Examples of blockchain payments are those settled with an external service, while examples of internal transactions are those settled with a Coins wallet.
  • transaction_ref - Contains the transaction ID for blockchain payments. For internal payments, it contains the payment ID.

Refund

It is possible that a cash out may fail delivery. For example, a pick up outlet may reject a cash out if the provided details are incorrect (ie. the given recipient address does not match the recipient's ID, etc.). Payment made for these cash outs will then be refunded back to the sender.

  • is_refunded - A property of the cash out which denotes whether the cash out has been refunded or not.

Additionally for sell orders with outlet id coins_transfer, there will be more details to determine why the transaction failed. Under the settlement object and failure_reason field, the following values might arise if the sell order has failed:

failure_reasonDescription
Target Address not FoundOccurs when the recipient's email address or phone number does not exist in the Coins.ph system.
Target Address is invalidOccurs when the format of the recipient's email address or phone number is invalid
Target address is inactiveOccurs when the recipient's account has been deactivated or closed already
Exceed recipient's account limitsOccurs when the recipient does not have sufficient cash-in limits to accept the disbursement
Insufficient balanceOccurs when the sender does not have sufficient balance to perform the coins transfer

Sample below:

"settlements": [
                {
                    "amount": "700",
                    "currency": "PHP",
                    "failure_reason": "Target address not found.",
                    "id": "298cd7da860348368745e5754c691e33",
                    "settled_at": null,
                    "status": "refunded",
                    "transaction_reference": ""
                }
            ]

Delivery

A successfully delivered cash out may have claiming details in order for the recipient to receive the funds. For example, pawnshops require the recipient to present a claiming number, and the name of the person who delivered the funds. This information can be found at the settlement_detail of a cash out. Additionally, settlement history can be found at the settlements array of a cash out. Settlements are representations of payment/s made by coins to the recipient of a cash out.

settlement_detail

Cash out options that require claiming details will have this property filled up. For cash out options that do not require claiming details (ie. bank), this will usually be empty.

  • actual_deposit_amount - The amount that the recipient will receive with fees already deducted, if any.
  • confirmation_code - A claiming code which the recipient needs to present to the pick up option in order to claim funds from the cash out.
  • delivered_by - Name of the person who delivered the cash out to a pick up option. This is usually required by pawnshops.
  • notes - Additional notes that a recipient may need to know in order to claim funds from the cash out.

settlements

This array contains the history of settlements made by coins to the recipient. A settlement object has the following properties:

  • currency - ISO 4217 currency code of the settlement's amount.
  • amount - The amount delivered by coins for the recipient.
  • id - The settlement's unique identifier.
  • settled_at - Date when the payment has been delivered in unix epoch.

Refund

It is possible that a cash out may fail delivery. For example, a pick up outlet may reject a cash out if the provided details are incorrect (ie. the given recipient address does not match the recipient's ID, etc.). Payment made for these cash outs will then be refunded back to the sender. Our operations and support team will then contact the sender to tell them the reason why the cash out needed to be refunded.

  • is_refunded - A property of the cash out which denotes whether the cash out has been refunded or not.
Language