# Alipay Merchant Registration Notification API

This document describes the Alipay+ Merchant Registration Notification webhook API that receives registration status updates from Alipay+.

## Endpoint

```
POST /api/alipay/notify_registration_status
```

## Request Headers

The webhook requires the following headers for security verification:

- `Content-Type: application/json`
- `signature: algorithm=RSA256,keyVersion=1,signature={signature}`
- `client-id: {your_client_id}`
- `response-time: {ISO8601_timestamp}`

## Request Payload

```json
{
  "registrationRequestId": "2020091811058602000006001420000",
  "referenceMerchantId": "2188120000190000",
  "referenceStoreId": "340000",
  "registrationResult": {
    "registrationStatus": "COMPLETED"
  },
  "pspRegistrationResultList": [
    {
      "productCodes": ["IN_STORE_PAYMENT"],
      "pspName": "ALIPAY_CN",
      "registrationResult": {
        "registrationStatus": "REJECTED",
        "rejectionReason": "rejectionReason message"
      }
    },
    {
      "productCodes": ["CASHIER_PAYMENT"],
      "pspName": "ALIPAY_CN",
      "registrationResult": {
        "registrationStatus": "APPROVED"
      }
    }
  ]
}
```

### Field Descriptions

- `registrationRequestId`: Unique identifier for the registration request
- `referenceMerchantId`: Merchant identifier in your system
- `referenceStoreId`: Store identifier (optional)
- `registrationResult.registrationStatus`: Overall registration status
  - `COMPLETED`: Registration approved
  - `REJECTED`: Registration rejected
  - `PENDING`: Registration still pending
- `pspRegistrationResultList`: Array of PSP-specific registration results
  - `productCodes`: Array of product codes (e.g., "IN_STORE_PAYMENT", "CASHIER_PAYMENT")
  - `pspName`: Payment service provider name (e.g., "ALIPAY_CN")
  - `registrationResult.registrationStatus`: PSP-specific status ("APPROVED", "REJECTED")
  - `registrationResult.rejectionReason`: Reason for rejection (if applicable)

## Response

### Success Response (200 OK)

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Notification received"
  }
}
```

### Error Response (400 Bad Request)

```json
{
  "result": {
    "resultCode": "FAIL",
    "resultMessage": "Invalid signature or processing error"
  }
}
```

## Data Storage

The webhook stores registration data in the `merchant_enrollments` table with the following mapping:

- `provider`: Always "alipay"
- `status`: Mapped from registrationStatus:
  - "COMPLETED" → "approved"
  - "REJECTED" → "rejected"
  - "PENDING" → "pending"
- `registration_params`: Original request identifiers
- `registration_response`: Complete notification payload
- `products`: PSP registration results indexed by PSP name
- `group_id`: Linked to merchant group by referenceMerchantId

## Error Conditions

The webhook will return a 400 error in the following cases:

1. Missing required fields (`registrationRequestId`, `referenceMerchantId`)
2. Missing or invalid signature headers
3. Signature verification failure
4. JSON parsing errors

## Testing

Use the integration test script located at `/tmp/test_integration.sh` to test the webhook with sample payloads.

## Security

- All requests must include valid signature headers
- Signature verification follows Alipay+ security standards
- Request payloads are logged for audit purposes