> ## Documentation Index
> Fetch the complete documentation index at: https://integration.wpay.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# PayTo via the API

To handle PayTo via the API directly, follow the [quick start guide](/guides/payments/direct-api/quick-start) on
direct API integrations, or use the steps below.

## Create a transactions

To create a PayTo transaction, set the `method` to `payto` and the `redirect_url` to the endpoint of your app that can handle the customer returning once they've completed approving the transaction on `payto.wpay.io`.

See the [`POST /transactions`](/reference/transactions/new-transaction) API endpoint for more details.

<CodeGroup>
  ```csharp C# theme={"system"}
  var transaction = await _client.Transactions.CreateAsync(
      transactionCreate: new TransactionCreate()
      {
          Amount = 1299,
          Currency = "AUD",
          Country = "AU",
          Intent = "capture",
          PaymentMethod =
              TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
                  new RedirectPaymentMethodCreate()
                  {
                      Method = "payto",
                      RedirectUrl = "https://example.com/callback",
                  }
              ),
      }
  );
  ```

  ```go Go theme={"system"}
  amount := int64(1299)
  currency := "AUD"
  method := "payto"
  intnet := "capture"
  redirectUrl: "https://example.com/callback"

  redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
      Method: method,
      RedirectUrl: redirectUrl
  }
  paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

  transactionCreate := components.TransactionCreate{
      Amount:        amount,
      Currency:      currency,
      Intent:        intent,
      PaymentMethod: &paymentMethod,
  }

  transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)

  // handle response
  ```

  ```java Java theme={"system"}
  CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
      .transactionCreate(TransactionCreate.builder()
          .amount(1299L)
          .currency("AUD")
          .intent("capture")
          .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
              .method("payto")
              .redirectUrl("https://example.com/callback")
              .build()))
          .build())
      .call();

  Transaction transaction = transactionResponse.transaction().orElse(null);

  // handle response
  ```

  ```php PHP theme={"system"}
  $transactionCreate = new TransactionCreate(amount: 1299, currency: 'AUD', paymentMethod: new RedirectPaymentMethodCreate(method: 'payto', redirectUrl: 'https://example.com/callback'));
  $response = self::$sdk->transactions->create($transactionCreate);
  $transaction = $response->transaction;
  ```

  ```python Python theme={"system"}
  transaction: models.Transaction = client.transactions.create(
      amount=1299,
      currency="AUD",
      intent="capture",
      payment_method={
          "method": "payto",
          "redirect_url": "https://example.com/callback",
      }
  )
  ```

  ```ts TypeScript theme={"system"}
  const transaction = await gr4vy.transactions.create({
      amount: 1299,
      currency: "AUD",
      intent: "capture",
      paymentMethod: {
      method: "payto",
      redirectUrl: "https://example.com/callback"
    }
  })
  ```
</CodeGroup>

<Warning>
  Please note that, when using PayTo, the `intent` must be set to `capture`.
</Warning>

If successful, the response of this transaction includes a `status` set to `buyer_approval_pending` as well as a `payment_method.approval_url`.

<CodeGroup>
  ```json Response theme={"system"}
  {
      "type": "transaction",
      "id": "0c41c8df-27f4-480e-97f0-9401558ae25e",
      "status": "buyer_approval_pending",
      "intent": "capture",
      "payment_method": {
          "type": "payment-method",
          "method": "payto",
          "mode": "redirect",
          "approval_url": "https://payto.wpay.io?sessionId=08c9b322-4da5-4a6b-8826-2dff20927990",
         ...
      },
      "method": "payto",
      ...
  }
  ```
</CodeGroup>

## Handle redirect to PayTo

Your app needs to redirect your customer to Wpay
where they are required to set up the PayTo instrument and approve the payment.
To do so, redirect the customer to the `payment_method.approval_url`. After they've
authenticated themselves, the customer will be redirected back to the `redirect_url`
that you set when creating the transaction.

## Handle the return to your app

When the customer is redirected back to your app, the transaction status is not known.
Your application will therefore need to call our API to get the latest transaction status. To do this, your `redirect_url` will be appended with the `transaction_id`.

```
[redirect_url]?transaction_id=2f37e0d0-5549-42c4-9c5c-e03d5fa97148&transaction_status=capture_succeeded
```

<Warning>
  Although we also provide the `transaction_status` in this callback, it's
  recommended to also fetch the latest status via the API, as the status may
  have changed since.
</Warning>

After you've handled the redirect, you can display a message to your customer letting them know the result of the transaction.

## Fetch the latest status

Finally, after the transaction has been created your application can get the
latest details and status using the transaction ID received via the callback to
the redirect URL, or on direct callback from the API.

<CodeGroup>
  ```js cURL theme={"system"}
  curl -i -X GET "https://api.example.gr4vy.app/transactions/fe26475d-ec3e-4884-9553-f7356683f7f9" \
      -H "Authorization: Bearer [JWT_TOKEN]"
  ```

  ```js Node theme={"system"}
  const response = await client.getTransaction(transaction_id);
  console.log(response.data);
  ```

  ```python Python theme={"system"}
  response = client.GetTransaction(transaction_id)
  print(response)
  ```

  ```php PHP theme={"system"}
  $result = $apiInstance->getTransaction($transaction_id);
  echo $result;
  ```
</CodeGroup>

The transaction includes details about the payment method used and the status
of the transaction.

```json theme={"system"}
{
  "type": "transaction",
  "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "status": "capture_succeeded",
  "amount": 1299,
  "currency": "AUD",
  "payment_method": {
    "type": "payment-method",
    "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
    "method": "payto",
    ...
  },
  ...
}
```

<Info>
  Visit the [API reference documentation](/reference) for full details about the
  transaction resource, and any other API.
</Info>

## Webhooks

In order to receive timely updates regarding the status of your PayTo transactions please set up a PayTo webhook URL. In
the [PayTo Merchant Dashboard](https://www.payto.com/signin) create a webhook with that URL. Once set up you will be given a
webhook ID by PayTo, provide this back to the team.

## About tokenization

You can pass the `store=true` parameter to each request to vault a PayTo agreement for future use.
Once stored, you can use the vaulted PayTo instrument for future transactions.

### Store a payment method

To create a PayTo instrument without paying and save it in the customer's wallet
for future use, set the method to `payto` and the `redirect_url` to the endpoint
of your application that can handle the customer returning once they've completed setting up PayTo.

Please note that when using PayTo intent must be set to capture as delayed capture is not supported by PayTo.

See the [`POST /payment-methods`](/reference/payment-methods/new-payment-method) API endpoint for more details.

```sh theme={"system"}
curl -i -X POST "https://api.example.gr4vy.app/payment-methods" \
   -H "Authorization: Bearer [JWT_TOKEN]" \
   -d '{
  "method": "payto",
  "redirect_url": "https://example.com/return-url",
  "country": "AU",
  "currency": "AUD"
  ...
}'
```

If successful, the response of this payment method will include a `status` set to `buyer_approval_pending` as well as a `payment_method.approval_url`.

```json theme={"system"}
{
    "type": "payment-method",
    "id": "ad268be4-c4d3-4cde-9eac-8d0d7aa37018",
    "status": "buyer_approval_required",
    "method": "payto",
    "type": "payment-method",
    "mode": "redirect",
    "approval_url": "https://payto.wpay.io?sessionId=7f156bd2-b65a-4f74-8d5b-41c4e090cc81",
    ...
}
```

### Redirect to Wpay

Your application will need to redirect your customer to Wpay where they will be required
to set up and authorize the PayTo agreement. To do so, redirect the customer to the `approval_url`.
After they've completed the required steps, the customer will be redirected back to the `redirect_url` that
you set when creating the payment method.

### Handle the return to your app

When the customer is redirected back to your app, depending on your
checkout customer experience your application might need to call our API to get the
latest list of payment methods for the customer.

To do this, see the [`GET /payment-methods`](/reference/payment-methods/list-payment-methods) API endpoint for more details.

```sh theme={"system"}
curl -i -X GET "https://api.{gr4vy_id}.gr4vy.app/buyers/payment-methods" \
    -H "Authorization: Bearer [JWT_TOKEN]"
```

The response will list all the customer’s saved payment methods along with their details.

```json theme={"system"}
{
  "items": [
    {
      "type": "payment-method",
      "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
      "label": "0424 343 247",
      "method": "payto",
      "mode": "redirect",
      "currency": "AUD",
      "country": "AU",
      ...
    }
  ...
  ]
}
```