Skip to main content
PATCH
/
entities
/
{id}
Update Payment Method
curl --request PATCH \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityData": {
    "paymentMethod": {}
  },
  "relationships": [
    {}
  ],
  "metadata": {}
}
'
{
  "success": true,
  "id": "<string>",
  "entityType": "<string>",
  "entityData": {},
  "relationships": [
    {}
  ],
  "metadata": {},
  "updatedAt": "<string>"
}

​
Overview

Updates an existing payment method entity. This endpoint allows partial updates - you only need to provide the fields you want to change.

​
Endpoint

PATCH http://api.gu1.ai/entities/{id}

​
Authentication

Requires a valid API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
id
string
required
UUID of the payment method entity to update

​
Request Body

​
entityData
object
Container for payment method data to update
​
relationships
array
Array of relationships to add or update
​
metadata
object
Additional metadata to update

​
Example Requests

​
Update Card Expiration Date

curl -X PATCH "http://api.gu1.ai/entities/payment-method-uuid-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "paymentMethod": {
        "expiryMonth": "06",
        "expiryYear": "2026"
      }
    }
  }'

​
Add Fingerprint to Payment Method

curl -X PATCH "http://api.gu1.ai/entities/payment-method-uuid-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "paymentMethod": {
        "fingerprint": "abc123xyz456"
      }
    }
  }'

​
Update Holder Name

curl -X PATCH "http://api.gu1.ai/entities/payment-method-uuid-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "paymentMethod": {
        "holderName": "Jane Smith"
      }
    }
  }'

​
Add Metadata

curl -X PATCH "http://api.gu1.ai/entities/payment-method-uuid-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "isDefault": true,
      "addedVia": "mobile_app",
      "verifiedAt": "2024-12-23T10:00:00Z"
    }
  }'

​
Response

​
success
boolean
Whether the operation was successful
​
id
string
UUID of the updated payment method entity
​
entityType
string
Always "payment_method"
​
entityData
object
The complete updated payment method data
​
relationships
array
Array of relationships
​
metadata
object
Complete metadata after update
​
updatedAt
string
ISO 8601 timestamp of this update

​
Response Example

{
  "success": true,
  "id": "payment-method-uuid-123",
  "entityType": "payment_method",
  "entityData": {
    "paymentMethod": {
      "type": "credit_card",
      "last4": "4242",
      "brand": "visa",
      "expiryMonth": "06",
      "expiryYear": "2026",
      "holderName": "John Doe",
      "issuerCountry": "BR",
      "bin": "424242",
      "funding": "credit",
      "fingerprint": "abc123xyz456"
    }
  },
  "relationships": [
    {
      "targetEntityId": "person-uuid-123",
      "relationshipType": "owns",
      "strength": 1.0
    }
  ],
  "metadata": {
    "isDefault": true,
    "addedVia": "mobile_app",
    "verifiedAt": "2024-12-23T10:00:00Z"
  },
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-12-23T10:15:00.000Z"
}

​
Use Cases

​
Update Expired Card

async function updateExpiredCard(paymentMethodId, newExpiry) {
  const response = await fetch(
    `http://api.gu1.ai/entities/${paymentMethodId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entityData: {
          paymentMethod: {
            expiryMonth: newExpiry.month,
            expiryYear: newExpiry.year
          }
        },
        metadata: {
          updatedReason: 'card_renewal',
          updatedAt: new Date().toISOString()
        }
      })
    }
  );

  return await response.json();
}

// Usage
await updateExpiredCard('payment-method-uuid-123', {
  month: '12',
  year: '2027'
});

​
Mark as Default Payment Method

async function setDefaultPaymentMethod(personId, paymentMethodId) {
  // First, remove default flag from all other payment methods
  const listResponse = await fetch(
    `http://api.gu1.ai/entities?entityType=payment_method&relationshipWith=${personId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const { entities } = await listResponse.json();

  // Update all to not default
  await Promise.all(
    entities.map(pm =>
      fetch(`http://api.gu1.ai/entities/${pm.id}`, {
        method: 'PATCH',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          metadata: { isDefault: false }
        })
      })
    )
  );

  // Set new default
  const response = await fetch(
    `http://api.gu1.ai/entities/${paymentMethodId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        metadata: { isDefault: true }
      })
    }
  );

  return await response.json();
}

​
Add Verification Status

async function markPaymentMethodVerified(paymentMethodId, verificationData) {
  const response = await fetch(
    `http://api.gu1.ai/entities/${paymentMethodId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        metadata: {
          verified: true,
          verifiedAt: new Date().toISOString(),
          verificationMethod: verificationData.method,
          verificationId: verificationData.id
        }
      })
    }
  );

  return await response.json();
}

​
Error Responses

​
404 Not Found

{
  "error": "Entity not found",
  "entityId": "payment-method-uuid-123"
}

​
400 Bad Request

{
  "error": "Invalid update data",
  "details": {
    "entityData.paymentMethod.expiryMonth": "Must be between 01 and 12"
  }
}

​
401 Unauthorized

{
  "error": "Invalid or missing API key"
}

​
Important Notes

  • This is a partial update endpoint - only fields provided will be updated
  • Other fields will remain unchanged
  • To remove a field, explicitly set it to null
  • Updates to sensitive fields (like card numbers) may be restricted
  • The updatedAt timestamp is automatically set to the current time
  • Risk scores may be recalculated after updates
  • Related transactions are not affected by payment method updates

​
See Also