Gatewayd connects transactions outside the ripple network to transactions on the ripple ledger. When you record a payment that occured external to the ripple ledger that payment sent as a corresponding ripple payment. To match an external payment from one of your users to a ripple payment, first register that user's ripple address in the system, and record the external payment in the external account for that user:
bin/gateway register_user <username> <password> <ripple_address>
POST /v1/registrations
{
"name": "[email protected]",
"password": "s0m3supe&$3cretp@s$w0r*",
"ripple_address": "r4EwBWxrx5HxYRyisfGzMto3AT8FZiYdWk"
}
gatewayd.api.registerUser({
"name": "[email protected]",
"password": "s0m3supe&$3cretp@s$w0r*",
"ripple_address": "r4EwBWxrx5HxYRyisfGzMto3AT8FZiYdWk"
}, function(error, user) {
// includes:
// user.external_account
// user.hosted_address
// user.ripple_address (independent)
};
Once a user is registered their account includes several additional records, including an external account to which they can make deposits, a hosted ripple address, and their independent ripple address. From then on any deposits made to that user's external account will be replicated to the ripple account and sent to their independent wallet. For instance:
bin/gateway record_deposit <amount> <currency> <external_account_id>
POST /v1/deposits
{
"external_account_id": 307,
"currency": "BTC"
"amount": "10.7"
}
gatewayd.api.recordDeposit({
"external_account_id": 307,
"currency": "BTC"
"amount": "10.7"
}, function(error, deposit) {
// do something with deposit
});
Though a gateway should always connect an external transaction to a ripple transaction, there may be a time when the gateway operator wishes to issue currency to a ripple address without a corresponding external transaction. To perform such an action use the enqueue outgoing payment api call:
POST /v1/payments/outgoing
{
"amount": 6.5,
"currency": "BTC",
"address": "r4EwBWxrx5HxYRyisfGzMto3AT8FZiYdWk"
}
gatewayd.api.enqueueOutgoingPayment({
"amount": 6.5,
"currency": "BTC",
"address": "r4EwBWxrx5HxYRyisfGzMto3AT8FZiYdWk",
}, function(error, payment) {
// do something with enqueued payment
});
not yet implemented
Gatewayd also monitors for payments made to its ripple address, and it will mark payments made to a user's hosted address as a withdrawal request, allowing the administrator to manually or programatically process and clear the withdrawal. In order to make a withdrawal payment on ripple, send to the user's hosted address including the destination tag component of their hosted address. Gatewayd will map the user's destination tag to their external (bank) account and enqueue a pending withdrawl for the administrator to process.
bin/gateway list_queued_withdrawals
GET /v1/withdrawals
gatewayd.api.listQueuedWithdrawals(function(error, withdrawals) {
// withdrawals is an array of external transaction records
});
Once the gateway administrator has processed the withdrawal request they can mark the withdrawal as cleared in the system with an api call.
bin/gateway clear_withdrawal <id>
POST /v1/withdrawals/:id/clear
gatewayd.api.clearWithdrawal(id, function(error, withdrawal) {
// withdrawal will be marked as "cleared"
});