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

# Arcus - SPEI

> Connect to Arcus to accept SPEI bank transfer payments in Mexico.

Arcus is a payment provider that enables merchants to accept SPEI (Sistema de Pagos Electrónicos Interbancarios) bank transfers in Mexico. SPEI is a push payment method where the buyer sends a payment to a CLABE number.

## Setup

Arcus does not provide self-service sign-up for a sandbox account. Please reach out to
[Arcus](https://arcusfi.com) to set up an account.

## Credentials

When setting up SPEI via Arcus in the dashboard, configure the following credentials. You can request these details via your Arcus dashboard once you are set up with an account.

* **Customer ID** - Your merchant account identifier.
* **User Name** - Your API username used to connect to the Arcus API.
* **Password** - Your API password used to connect to the Arcus API.
* **Subscription Secret** (optional) - A secret value you define to verify webhooks received from Arcus. See [Webhooks](#webhooks) below.

## Supported countries

Arcus supports transactions from buyers in `MX`.

## Supported currencies

Arcus supports processing payments in `MXN`.

## Limitations

The following features are not supported by this connector:

* **Delayed capture** - Authorization and capture happen together
* **Partial capture** - Capturing a portion of the authorized amount is not supported
* **Partial refunds** - Partial refunds are not supported
* **Refunds** - Refunds are not supported
* **Void** - Canceling a transaction is not supported
* **Payment method tokenization** - Storing payment methods for future use is not supported
* **Zero auth** - Zero-dollar verification transactions are not supported
* **Network tokens** - Network tokenization is not supported
* **3-D Secure** - 3DS authentication is not applicable
* **Transaction sync** - Automatic transaction status synchronization is not supported
* **Settlement reporting** - Automatic settlement reporting is not supported

Additional push payment limitations:

* A buyer may never send a payment for various reasons, including when they copy over the CLABE number incorrectly.
* A buyer may send the wrong amount, resulting in either an over or under payment. The `capture_amount` is marked accordingly.
* A buyer may send multiple payments for the same CLABE number. The system does not handle this situation, but it is monitored and the support team is notified.

## Webhooks

The Arcus SPEI connector requires webhooks to be set up from Arcus to receive payment confirmations.

To configure webhooks:

1. Set up the connector in the dashboard, defining a secret value as the **Subscription Secret**.
2. Copy the webhook subscription URL shown in the dashboard once the connection is set up.
3. Use the Arcus [`POST /notification-subscriptions`](https://developers.arcusfi.com/docs/paas/events/operations/create-a-notification-subscription) API endpoint with the webhook URL and the `subscription_secret` you set earlier.

```json theme={"system"}
{
  "url": "https://api.example.spider.gr4vy.app/i/Xz9q_HKzTSe4CN_0lRA9jmFyY3Vc3BlaQ/R6DEA6oG3vtPI=OSU1PsRS9lmn4z-jey-SrY",
  "description": "Notifications - Sandbox",
  "subscription_secret": "my-super-secret-value",
  "subscribed_events": [
    "accounts.transactions.type.credit"
  ]
}
```

## Integration

SPEI is a push payment method. Any SPEI transaction created returns a `transaction` resource with a `status` of `processing` and a `payment_method.approval_url`. This approval URL can be displayed in a popup, iframe, or redirected to, but buyers are not redirected back to the `redirect_url` you provided when the transaction was created.

Once the buyer makes the payment to the CLABE number provided on the hosted screen, a webhook is sent from Arcus to the system, after which the status of the transaction is updated and your system is notified via a webhook.

Start by creating a new transaction with the following required fields.

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

  ```go Go theme={"system"}
  amount := int64(1299)
  currency := "MXN"
  country := "MX"
  method := "spei"
  redirectUrl := "https://example.com/callback"

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

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

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

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

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

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

  ```python Python theme={"system"}
  transaction: models.Transaction = client.transactions.create(
    amount=1299,
    currency="MXN",
    country="MX",
    payment_method={
      "method": "spei",
      "redirect_url": "https://example.com/callback",
    }
  )
  ```

  ```ts TypeScript theme={"system"}
  const transaction = await client.transactions.create({
    amount: 1299,
    currency: "MXN",
    country: "MX",
    paymentMethod: {
      method: "spei",
      redirectUrl: "https://example.com/callback"
    }
  })
  ```
</CodeGroup>

After the transaction is created, the API response includes a `payment_method.approval_url` and the status is set to `processing`.

```json theme={"system"}
{
  "type": "transaction",
  "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
  "status": "processing",
  "payment_method": {
    "type": "payment-method",
    "approval_url": "https://cdn.gr4vy.com/connectors/..."
  },
  "method": "spei"
}
```

Display the `approval_url` to the buyer (in a popup, iframe, or redirect) so they can view the CLABE number and complete the payment through their bank.