gatewayd_simple_guide.md

Simple Gatewayd User's Guide

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:

Register User

Command Line

bin/gateway register_user <username> <password> <ripple_address>

REST

POST /v1/registrations
{
  "name": "steven@ripple.com",
  "password": "s0m3supe&$3cretp@s$w0r*",
  "ripple_address": "r4EwBWxrx5HxYRyisfGzMto3AT8FZiYdWk"
}

Javascript

gatewayd.api.registerUser({
  "name": "steven@ripple.com",
  "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:

Record Deposit

Command Line

bin/gateway record_deposit <amount> <currency> <external_account_id>

REST

POST /v1/deposits
{
  "external_account_id": 307,
  "currency": "BTC"
  "amount": "10.7"
}

Javascript

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:

Enqueue Outgoing Payment

REST

POST /v1/payments/outgoing
{
  "amount": 6.5,
  "currency": "BTC",
  "address": "r4EwBWxrx5HxYRyisfGzMto3AT8FZiYdWk"
}

Javascript

gatewayd.api.enqueueOutgoingPayment({
  "amount": 6.5,
  "currency": "BTC",
  "address": "r4EwBWxrx5HxYRyisfGzMto3AT8FZiYdWk",
}, function(error, payment) {
  // do something with enqueued payment
});

Command Line

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.

List Queued Withdrawals

Command Line

bin/gateway list_queued_withdrawals

REST

GET /v1/withdrawals

Javascript

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.

Clear Withdrawal

Command Line

bin/gateway clear_withdrawal <id>

REST

POST /v1/withdrawals/:id/clear

Javascript

gatewayd.api.clearWithdrawal(id, function(error, withdrawal) {
    // withdrawal will be marked as "cleared" 
});